On this page

Synopsis

icomposite [-v] [-w width] [-h height] [-f] [-c] [command]

Composites layers of images, provides some simple image processing, and resizes images. Arbitrary filters can be specified when scaling images.

Options

-v

Operate verbosely by outputting the current scanline and the current composite sub-operation as they are executed.

-w width

The output horizontal resolution is set to width.

-h height

The output vertical resolution is set to height. Normally, all frames are scaled in X and Y to match the resolution of the largest input image. Occurrence of either the width or the height options, cause the input and output frames to be scaled to the specified values, while the vertical resolution is set to preserve the width/height ratio of the largest input image.

-f

The input images are filtered (using a box filter) to the desired output resolution. Normally, the input images are sampled. Filtering takes longer than sampling, but gives better results when scaling images.

-c

Normally, ic will terminate the current composite operation if an error occurs when opening or reading an image file. The -c option indicates that the composite operation should continue even if such an error occurs. If this happens, a blank image is loaded in place of the one which caused the error. Note that this may cause the resulting composite to be incorrect.

-B

Backwards compatible (Houdini 2.5 and prior) image scaling. No extra filter support.

-F

Specify filter type for reading of images (entering "icomposite -" lists the available filters).

command

Any single input line which can be supplied to ic in interactive mode can also be supplied here.

Composite Operators

A unary operator is applied to one image such as:

claw.pic over back.pic

The 0.7 is a Constant, a positive real number. Constants, except those used in a constant image, cannot exceed one.

A constant image is an image containing one solid color. It may be included as a composite element (typically for use as a background element) and is specified as red, green, blue and, optionally, alpha values enclosed within square brackets:

[1 0.7 0.5] [0.8 0.5 0.4 0.8]

The second example includes alpha. In the first example, alpha is not present and defaults to one. The constants should be real values in the range zero to one.

dissolve value image

The subject image is dissolved by the amount given as the constant with the operator. This means that the red, green, blue and alpha channels are all multiplied by the supplied value.

darken value image

The subject image is darkened by the amount given as the constant with the operator. This means that only the red, green and blue channels are multiplied by the supplied value. The alpha channel is left unmodified by the darken operator.

opaque value image

Only the alpha channel of the subject image is multiplied by the amount given as the constant with the operator. This has the effect of creating a luminescent element which adds color information without obscuring the background elements.

mono value image

The subject image is made more monochrome by the amount given, where one is fully monochrome, zero leaves the colors unchanged, and values between result in partially monochrome images.

gamma value image

Gamma correction is applied to each of R, G and B of the subject image. A value more than one makes the picture brighter, and vice versa.

channel chans image

The subject image has its channels copied, swapped or replaced according to the combination and order of the four characters in the supplied chan string.

The first character represents what is placed in the output red channel, the second character the output green channel, etc.

The character r represents the input red channel, z represents a channel containing zero (black), and o represents a channel containing one (full value).

For example, bbba copies blue into the red and green channels, while blue and alpha remain unchanged. rgba leaves the picture unchanged. aaaz copies alpha into the rgb channels and zero in the alpha channel.

alpha value image

The subject image has its red, green and blue channels multiplied by its alpha channel.

setup value image

The subject image is boosted by value in pixels where alpha is greater than zero, and is untouched where alpha is zero. The setup operator will boost low luminance levels of an image (based on alpha) to be above the given lower limit, usually to accommodate zero-black keying. For example:

icomposite abekas:34.rgb = setup .075 claw.pic

If there is non-zero alpha in a pixel, the luminance would be boosted to be a minimum of .075. Any colors in the image over .075 luminance would remain unchanged.

even image

Maintain only the even scanlines of the subject image (i.e. erase all odd scanlines to black). Since ntsc frames result in the bottom scanline being odd, this operator assumes that the first scanline of an image file is odd.

odd image

Maintain only the odd scanlines of the subject image (i.e. erase all even scanlines to black). Since ntsc frames result in the bottom scanline being odd, this operator assumes that the first scanline of an image file is odd.

image cross image

The cross operator is the only binary operator which requires a constant operator value. This operator performs a cross-dissolve of two elements. The operation "A cross 0.4 B" is equivalent to dissolve 0.6 A plus dissolve 0.4 B. It is provided as a separate operator for efficiency and convenience.

image over image

The over operator is likely the most commonly used composite operation. It places its left operand over top of its right operand. The foreground element survives everywhere, while the background element survives only where the foreground does not have full coverage.

image plus image

The plus operator results in the simple addition of each channel of the left and right operands. The sums are clipped to the maximum channel value.

image minus image

The minus operator results in the simple subtraction of each channel of the right operand from the left operand. The results are clipped to the minimum channel value of zero.

image diff image

The diff operator results in the absolute value of the difference between the right operand from the left operand.

image multiply image

The multiply operator results in the simple multiplication of each channel of the left and right operands. Channel values are treated as fixed point values between zero and one for the purposes of this operator.

image inside image

The inside operator results in the survival of the left operand anywhere that the right operand has coverage.

image outside image

The outside operator results in the survival of the left operand anywhere that the right operand does not have coverage.

image atop image

The atop operator places its left operand atop its right operand. The result is that the left operand survives wherever the right operand has coverage and elsewhere only the right operand survives. Thus, A atop B is the union of A inside B and B outside A.

image xor image

The xor (exclusive or) operator provides the union of A outside B and B outside A. In other words, the result is everything that does not overlap in the two elements.

Grammar

icomposite has a formal grammar. The allowed syntax is defined by the following. The unary operators dissolve, darken, opaque, mono, gamma, alpha, even and oddhave equal precedence which is higher than the binary operators. Binary operators are left associative (i.e. a over b over c is equivalent to (a over b) over c).

Composite: FILENAME = Expression
Expression: FILENAME
            | Constant_Frame
            | dissolve Constant Expression
            | darken Constant Expression
            | opaque Constant Expression
            | mono Constant Expression
            | gamma Constant Expression
            | channel Channels Expression
            | alpha Expression
            | even Expression
            | odd Expression
            | Expression cross Constant Expression
            | Expression plus Expression
            | Expression minus Expression
            | Expression diff Expression
            | Expression multiply Expression
            | Expression over Expression
            | Expression atop Expression
            | Expression outside Expression
            | Expression inside Expression
            | Expression xor Expression
            | (Expression)

Constant_Frame: [Constant Constant Constant Constant]
                | [Constant Constant Constant]

icomposite performs compositing operations as described in the paper "Compositing Digital Images" (Computer Graphics, Volume 18, Number 3, Thomas Porter and Tom Duff, July 1984). All elements used in composite operations (except the alpha operator, described below) assume that the red, green and blue channels have been pre-multiplied by their corresponding alpha channel as do most renderers. This means that frames without pre-multiplied r, g, b channels cannot be used directly in composite operations, except possibly as background elements.

The alpha operator converts a non-pre-multiplied image into the required pre-multiplied format. Thus, any frames without pre-multiplied color channels should first have the alpha operator applied to them (see examples below).

Example

icomposite ip = mono .5 $HH/pic/Mandril.pic

icomposite Either gets one command from the command line or it reads image composite sentences from its standard input and performs the operations required to generate the requested composite image.

When reading commands interactively, each line of input is a single composite operation or sentence. Environment variables denoted with a leading $ are first expanded.

The following are some examples of composite sentences which may be provided as input to ic. Some samples are fairly complex. The use of (…) signals to ic to do the operations between parentheses first. The use of [...] means it is an image with a constant color given by the three rgb or four rgba numbers inside:

cd $HFS/demo/ImageTools
ip = claw.pic over back.pic
junk.pic = claw.pic outside back.pic
ip = dissolve .5 claw.pic over ([0.3 0.1 0.1 0.25] atop back.pic)
ip = marble.pic multiply [.5.7 1] 
ip = back.pic minus [0.25 0 0] over [0.3 0.2 0.1]
fields.pic = even claw.pic plus odd back.pic over [.2.1.1]
ip = (darken 0.7 (object.pic inside shadow.matte) atop 
object.pic) over .bg.pic
ip = (marble.pic cross 0.7 air.pic) outside claw.pic over 
back.pic
ip = gamma 1.3 back.pic
icomposite -F gauss -w 640 -h 486 ip = $HH/pic/Mandril.pic
icomposite -F box -w 640 ip = $HH/pic/Mandril.pic

Interactive Composite Mode

If no composite command is given on the command line, icomposite goes into its interactive mode where the user can type many commands. If input is from a terminal then icomposite prompts for a composite sentence with the string =>.

Press ⌃ Ctrl + C to terminate the command unless a composite operation is under way, in which case only the in-progress composite is interrupted. If it is not being run interactively, then interrupt signals will always terminate the command.

Each input line is individually interpreted until the end of file is reached.

An input line starting with the character '!' is interpreted as a shell command and executed.

Notes

  • icomposite does not accept file names containing any of the following characters:

    [] () = ; !
    

    …or filenames that look like a real number (e.g. 123).

  • Errors are handled very simplistically, so you will typically get something like, "Syntax error on line 1".

Stand-alone utilities

  • abcconvert

    Convert between Alembic formats.

  • abcecho

    Print information about an Alembic file.

  • abcinfo

    Print information about an Alembic file.

  • chchan

    Copies channel collection to/from action channel format.

  • chcp

    Copies channel collection file to another format.

  • chinfo

    Prints information about a channel collection file.

  • claudio

    Copies CHOP data (clip) to/from audio formats.

  • clchan

    Copies CHOP data (clip) to/from action channel format.

  • clchn

    Copies CHOP data (clip) to/from channel collection format.

  • clcp

    Copies CHOP data (clip) to another format.

  • clinfo

    Prints information about a CHOP data (clip) file.

  • dsmconvert

  • dsmmerge

  • dsparse

    Parses and displays dialog scripts.

  • gabc

    Convert between Alembic and Houdini geometry.

  • gconvert

    Convert between Houdini polygon formats.

  • gdxf

    Converts DXF polygons to/from Houdini format.

  • geps

    Converts EPS files to Houdini polygon format.

  • giges

  • ginfo

    Prints polygon file statistics.

  • glightwave

    Converts LightWave files to/from Houdini format.

  • gplay

    Geometry viewer.

  • gptex

    Makes a ptexture image file from a geometry file.

  • greduce

    Reduces polygons in a file.

  • gwavefront

    Converts .obj files to/from Houdini format.

  • hbrickmap

    Converts an i3d file or volume primitive geo/bgeo file into a Pixar brickmap file.

  • hcollapse

    Collapses a directory structure.

  • hcpio

  • hexpand

    Expands hip files into a directory structure.

  • hrender

  • hsc

  • hscript

    Command line HScript interpreter.

  • i3dconvert

  • iautocrop

    Crops images based on pixel values.

  • icineon

    Convert images from 10-bit Cineon format to an 8 bit format.

  • icomposite

  • iconvert

    Converts image formats.

  • icp

    Isolate a region of an image in a new image.

  • iflip - Flip Image

  • ihot

    Scans an image for video-unsafe colors.

  • iinfo

    Outputs information about an image.

  • ilut

    Generates a lookup table (LUT) from standard channel formats or another LUT.

  • ilutcomp

    Generates a single lookup table (LUT) from from two LUTs.

  • ilutinfo

    Prints information about a lookup table (LUT) file.

  • imdisplay

    Sends an image to an mdisplay window.

  • iprint

    Prints the RGBA values for an image as text.

  • iquantize

    Reduces the number of colors in an image.

  • isixpack

    Generates an environment/reflection map from six images representing the six sides of a cube, or a cross image.

  • itilestitch

    Assemble a series of image files with crop windows into a single image.

  • izg

    Converts Z-depth images to 8-bit grayscale images.

  • izmatte

    Composites RGB and Z-depth images.

  • mcacclaim

    Converts an Acclaim motion file to a Houdini script and channel file(s).

  • mcbiovision

    Converts a BioVision motion file to a Houdini script and channel file(s).

  • mcmotanal

    Converts a Motion Analysis TRC motion file to a Houdini script and channel file(s).

  • mcp

    Convert an image sequence to a movie file.

  • minfo

    Prints information about movie files.

  • siminfo

    Prints simulation cache file statistics.

  • spy

    Shell utility for navigating the UNIX filesystem.

  • vexcache

    Query or modify the VEX compile cache.

  • vexexec

    Execute a cvex shader.