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.

  • geodiff

    Display Geometry Differences.

  • geps

    Converts EPS files to Houdini polygon format.

  • giges

  • ginfo

    Prints polygon file statistics.

  • glightwave

    Converts LightWave files to/from Houdini format.

  • gpdb

    Converts .pdb files to/from Houdini format.

  • gplay

    Geometry viewer.

  • gply

    Converts .ply files to/from Houdini format.

  • gptex

    Makes a ptexture image file from a geometry file.

  • greduce

    Reduces polygons in a file.

  • gwavefront

    Converts .obj files to/from Houdini format.

  • hcollapse

    Collapses a directory structure.

  • hcpio

  • hexpand

    Expands hip files into a directory structure.

  • hkey / License Administrator

    Opens a graphical user interface for viewing and managing licenses and license server options.

  • hoiiotool

    Swiss-army knife of image operation tools.

  • hotl utility

    Command line utility to work with .hda/.otl files.

  • hrender

  • hsc

  • hscript

    Command line HScript interpreter.

  • hserver

    Houdini communicates through this proxy server to the sesinetd licensing daemon.

  • htexcache

    Query or modify the disk texture cache.

  • husk

    Command line utility for rendering a USD file using Karma or some other Hydra client.

  • i3dconvert

  • iautocrop

    Crops images based on pixel values.

  • icineon

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

  • icomposite

  • iconvert

    Converts an image of one type to another type.

  • icp

    Isolate a region of an image in a new image.

  • idenoise

    Removes noise from an image file.

  • idiff

    Display Image Differences.

  • iflip - Flip Image

  • 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.

  • imaketx

    Creates mipmapped .exr or .rat textures from image files.

  • 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.

  • Launcher

    The Houdini Launcher downloads, installs, upgrades, and uninstall Houdini and its components.

  • 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.

  • mqserver

    Message Queue Server for PDG/TOPs

  • py23convert

    Convert Python 2 expressions in HDAs to Python 2/3.

  • renderstatsoverlay

    Generates a (possibly scaled down) version of a rendered image with render statistics baked in.

  • renderstatsreport

    Generates an HTML page containing render statistics from an EXR image.

  • sesictrl

    Sets Houdini license server options from the command line.

  • sesinetd

    The Houdini license server. This program runs in the background managing Houdini licenses.

  • siminfo

    Prints simulation cache file statistics.

  • spiff

    Display Text Differences.

  • spy

    Shell utility for navigating the UNIX filesystem.

  • usdview

    Command line utility for viewing and inspecting USD scenes.

  • vexcache

    Query or modify the VEX compile cache.

  • vexexec

    Execute a cvex shader.