IFDFormatDocument

From Odwiki

Jump to: navigation, search

Mantra IFD Language Reference

Please note that this is unofficial documentation. Side Effects may change the behaviour of the IFD in the future without warning.

Mantra IFD Language Reference

The IFD language is a subset of the hscript language without any of the OP or channel commands. It is augmented with a set of commands that can be used for defining scenes to be rendered. All variable and expression expansion supported by hscript is also supported in IFDs.

Because IFD parsing is done using the same parser as hscript, it is possible to use command aliases, variable expansion, expression evaluation, conditional statements and loop constructs in the IFD.

It should be made clear that the IFD format is not a fixed standard, which means that Side Effects Software reserves the right to change or augment the definition in future releases.

Commands common to IFD and hscript: (Further help for the following commands can be found in the Houdini reference manuals.)

  • alias - Create a command alias
  • break, continue - Break out of a loop, or continue to the next iteration of the loop
  • echo - Print something to the console
  • exhelp - Print help for available expressions
  • exit - Exit a command script (the top level script must use quit)
  • for, foreach, while - Loop structures
  • help - List commands
  • hip, job - Specify the value of the $HIP variable
  • history - Show a command history
  • if, else, endif - The hscript conditional execution construct
  • memory - Print the memory usage
  • prompt - This hscript command has no effect in IFDs
  • quit - Terminate execution of vmantra
  • read - Read a variable from the console
  • set - Set a local variable
  • setenv - Set a global variable
  • shift - Shift arguments
  • source, cmdread - Source a script file. Note: inline details, VEX shaders, etc. will not load properly from a sourced file. Details and shaders can be loaded from external files.
  • time - Time the execution of a command
  • ucd - Change the operating system's working directory
  • unix - Execute an external application
  • upwd - Query the operating system's working directory

Ray commands:

  • ray_alfred - Specifies that vmantra should generate progress reports in the form that is understood by Pixar's Alfred render queue manager.
  • ray_ambient - Obsolete command.
  • ray_aspect aspect_ratio - Specifies the pixel aspect ratio for the output image. This is the ratio of the width of a pixel to its height (not the width and height of the image).
  • ray_atmosphere name shader [shader_args...] - Defines an atmosphere object. Every atmosphere has a name associated with it. The shader is either a full path or simply the name (path searching will be performed) of a VEX shader.
  • ray_bounce [-t refract] [-w weight] raybounce - Specifies the maximum number of ray bounces allowed for the given object. The -t option can be used to specify a different number of bounces for refraction. The weight parameter is used to cull rays based on their contribution to the final pixel color rather than a fixed number of bounces (the minimum of the two limits is used). For example, setting a weight limit of 0.05 will cause no rays to be spawned unless they have a chance of contributing more than 5% to the final pixel color.
  • ray_bucketsize bucket_size - Specifies the size that mantra will use for rendering. Specifying a bucket size of 0 will choose the "best" bucket size for the rendering algorithm used.
  • ray_clip near far - Specifies the near and far camera clipping planes
  • ray_cmdopt options - Allows the script to set options to vmantra as if they were specified on the command line. The options specified by this command are reset when the ray_reset command is run.
  • ray_copmap cop_path binary|ascii - Loads an image inline. The raster data follows directly (starting on the next line of the IFD). The raster data should be in Houdini .pic format (though other formats that do not seek through the file are possible). The COP path is used for resolving references to COPs from within VEX shaders.
  • ray_crop x0 x1 y0 y1 - Specifies a crop region to be rendered. The arguments should be in the range 0.0 to 1.0 (representing the fraction of the image resolution).
  • ray_curvature curve_value - Specifies the lens curvature for "fish-eye" style lens distortion.
  • ray_dbound bound - Specifies the displacement bounds for the current object.
  • ray_detail [-s] [-b] filename - Specifies a geometry detail. The -s option causes normal interpolation on polygons. If normals don't already exist on the geometry, they will be computed internally. The -b option turns on backface removal for the detail. The filename can refer to any disk file or may also be "stdin". If the filename is "stdin", the geometry data should begin on the next line. The geometry data may be in any format that Houdini can read from stdin (i.e. .geo, .bgeo, .bpoly, etc.)
  • ray_displace shader_name shader_args... - Specifies a displacement shader for the current object
  • ray_dither args - Specifies the dither amount used in quantization. The dither level is specified for 8-bit quantization. When 16-bit images are rendered, the dither level used is the level specified divided by 255. No dithering is performed on floating point data.
  • ray_dof fstop focal_length focus - Specifies depth of field for the current image.
  • ray_even [-f] [image_name] / ray_odd [-f] [image_name] - Renders the even or odd video field for an image. The command either fills in the missing field in the specified image or generates a new image containg the first field. The -f option is used to flag that the first field is being rendered and should be rendered to the image name specified.
    • For example:
      • First field
      • ray_even -f /tmp/field1.pic
      • Second field
      • ray_odd /tmp/field1.pic
      • In the above example, the even field will be created in the temporary file /tmp/field1.pic. When rendering the second field, the even field will be merged.
  • ray_filter filtername xwidth [ywidth] - The pixel filter is specified with this command. The filter name can be any one of the standard Houdini filter types: box, gauss, point, sinc, bartlett, blackman, catrom, hanning. The filter is assumed to be square if the ywidth is not specified.
  • ray_gamma gamma_value - Specifies the gamma correction to be used in quantizing.
  • ray_jitter jitter_scale - Specifies the amount of jittering. The jitter scale should be between 0.0 and 1.0.
  • ray_lcomponent [-d] [-s] - Typically lights are used for both specular and diffuse illumination. The -d option will disable the light for diffuse illumination, the -s option will disable it for specular illumination.
  • ray_ldshader context filename - Allows a VEX shader to be pre-loaded. This is typically used internally for network rendering.
  • ray_light [-z zoom] [-Z zoomx zoomy] [-O orthox orthoy] [-n name] - Defines a light source. The light source can be nameed, though at the current time, there is no access to the name. The zoom and ortho options are used to define the field of view for the light source. These parameters are required in order to get accurate NDC coordinates for light and shadow shaders. The zoom parameter has the same derivation as the ray_zoom command. For non-square fields of view, the -Z option should be used. The equation to specify zoom is:
    • xzoom = focal_length / aperture
    • yzoom = xzoom * image_xres / image_yres
    • Or, if the projection is orthographic:
    • orthox = ortho_zoom;
    • orthoy = orthox * image_xres / image_yres
  • ray_lmask l0 l1 l2 - Each light defined is given a unique ID starting at 0 and incrementing by one for each light. The arguments to the ray_lmask command can be used to specify whether specific lights illuminate the current object. All lights are turned on by default. To turn a light off, specify the light source number prefixed with a negative sign. For example: ray_lmask -0 -3 -6 -7 Will turn off light 0, 3, 6, and 7 for the current object.
  • ray_material - Obsolete command.
  • ray_mtransform m00 m01 m02 m03 m10 ... m32 m33 - Turns on transformation motion blur for the current object. A 4x4 transform matrix is constructed from the 16 required arguments. The transform matrix should represent the position of the object at the end of the motion frame. At the current time, this command is only valid for geometry objects.
  • ray_object [-M] [-D] name geometry [deformed_geometry] - VEX mantra requires geometry to be instanced to appear in the renderer. The ray_object command defines an instance of the geometry. Optionally, two geometry details can be specified. The second detail should specify the geometry as it is deformed at the end of the motion frame. Each instance must be given a name (which is the first argument). The -M option causes this instance to ignore any surface shaders defined on the detail (i.e. ignore the vm_surface attribute). The -D option causes the object to ignore any displacement shaders defined on the detail (i.e. ignore the vm_displace attribute).
  • ray_octsplits level - Specifies the maximum recursion level in computing octrees. This parameter defaults to 15.
  • ray_phantom - Sets the current object to be a phantom object. This object will not be visible for primary rays (it will only cast shadows and appear in reflections/refractions).
  • ray_plate - PrMan has a "smooth" attribute to turn interpolation of vertices on/off. Mantra's equivalent is undocumented, but consists of putting the following statement in the post-include of the object you want: ray_plate. I'm pretty sure this only affects interpolation of the MicroPolygons -- it's intended for trying to match a background plate exactly during rendering (for which you want to turn off interpolation of MicroPolygon vertices).
  • ray_picture image_name - Specifies the output image name. The format and bit depth are inferred from the extension on the image name. The bit-depth can be overridden using the -b option to mantra.
  • ray_polyopt level - Specifies the polygon optimization level. The level should be a number between 0 and 4. A value of 4 will result in faster renders with possible interpolation errors, a level of 0 will result in the most accurate interpolation across polygons at a much larger rendering cost. The default value is 2.
  • ray_projection projection_type [options] - Specifies the method for projecting geometry onto the camera plane. The choices for projection_type are: perspective, spherical, cylindrical, ortho. Note: when ortho is specified, an ortho width must also be specified. This width specifies the viewing area of the camera. Only the first character of the projection type is required.
  • ray_quit - Terminates mantra.
  • ray_raysample samplex sampley - Sets the sampling level for secondary rays when rendering using the micro-polygon algorithm. The ray_sample command is used to specify the sampling level for primary rays.
  • ray_raytrace / ray_render - Renders the current scene
  • ray_reset [-o] [-l] [-f] [-d] [-c] - Resets the state of the renderer.
    • -o removes all current object definitions
    • -l removes all light definitions, resetting the light index counter.
    • -f removes all definitions of fog objects
    • -d removes all geometry definitions
    • -c removes all images defined by the ray_copmap command.
  • ray_resolution xres yres - Specifies the output resolution of the image.
  • ray_rmask pattern - Specifies the reflection mask for the current object. The specified pattern should be a simple regular expression. Only the asterisk, question mark (?), and carat (^) are supported in expansion (no group expansion is supported by mantra). All objects matching the pattern will be reflected in the current object.
  • ray_rusage args - Displays the current system resources used by mantra, which includes the current time, memory and other resource information (depending on the operating system).
  • ray_sample samplex sampley - Specifies the super-sampling level.
  • ray_shader shader_name shader_args... - If the last object defined was a light source, this command specifies the shader for the light source. If the last object defined was a geometry instance, the shader represents the surface shader.
  • ray_shadingrate [-d lod] shading_rate - The -d option specifies the level of detail for the current object. This is the refinement level used by the ray-tracing engine for NURBs and displacement-mapped surfaces. A higher level of detail will result in more refinement when ray-tracing (i.e. it is the inverse of the shading rate). The shading_rate parameter specifies the refinement level for micro-polygon rendering. The rate should be the inverse of the shading quality. Thus, a rate of 100 will render faster (and produce larger micro-polygons) than a shading rate of 1.
  • ray_shadow shader_name shader_args... - Specifies the shadow shader for the most recently defined light source.
  • ray_smask pattern - Specifies a shadow mask for the most recently defined light source. Like the reflection mask (ray_rmask), this pattern can only use the asterisk, question mark (?) and carat (^) symbols. Objects that match the pattern will cast shadows from the light.
  • ray_stransform m00 m01 m02 m03 m10 ... m32 m33 - Specifies the shader space for the current object. This transform should take the object space (not world space) and transform it into the shader space. Typically, this transformation is defined as an identity matrix (possibly with a negative z-scale). The shader space defines both the space for the surface and the displacement shader. This command is only valid for geometry objects.
  • ray_texcache [-a on|off] [-c] [-r xres yres] [-m max] [-l] [-s] [-v] - Controls the texture cache for non-RAT files in mantra. Note: This command has no effect on RAT file caching.
    • -a Turns auto-flushing of textures on. If a texture is completely de-referenced, it will be flushed from the texture cache, causing it to be re-loaded if it becomes referenced at a later time.
    • -c Clears the texture cache
    • -r Specifies the maximum resolution of an image allowed in the texture cache. Texture images that are larger than the resolution will be filter scaled to fit into the cache. The default is 16K by 16K.
    • -m Sets the maximum number of images that can be loaded into the cache at one time.
    • -l Lists the current contents of the texture cache. This command will list .rat files as well.
    • -v Sets the verbose option for the command.
  • ray_time time - Sets the value of the $T variable.
  • ray_tiny - Obsolete command.
  • ray_transfer transfer_file - This command allows individual gamma correction for each of the R, G, and B channels. The transfer_file should be a simple ASCII file containing three floating-point numbers on each line. The floating point numbers should be between zero and one. Each line in the transfer file represents a quantization level. Comments can be specified by using the octothorpe character (#).
  • ray_transform m00 m01 m02 m03 m10 ... m32 m33 - The 16 arguments specify the transform of the current object, light source or fog object at the beginning of the motion frame.
  • ray_unlink filename - This command provides an operating system independent way of removing a file from the file system. When generating reflection maps (using isixpack), the six component images may be removed using this command.
  • ray_verbose level - Sets the verbosity level of the renderer (i.e. the -V option)
  • ray_version VEXversion_number - As the .ifd extension is used by both mantra3 and VEX Mantra, the ray_version command allows for version testing. For VEX Mantra, the version specification should be prefixed by VEX.
  • ray_whitepoint level - Specifies the white point of the image (i.e. where a color value of 1, 1, 1 gets mapped to during quantization).
  • ray_window left right bottom top - Specifies a sub-window of the image plane which gets mapped to the full image. There is no perspective distortion with this transform.
  • ray_zoom zoom - The zoom is defined to be the focal_length divided by the aperture.

Structure of an IFD

There are really two types of commands in the IFD description. The first type has a global scope. The other type of command is local to the last defined object. Some of these commands are sensitive to the last type of object defined. 

Command         Geo     Light   Fog
ray_shader      Yes     Yes     Yes
ray_transform   Yes     Yes     Yes
ray_displace    Yes     No      No
ray_stransform  Yes     No      No
ray_bounce      Yes     No      No
ray_lmask       Yes     No      No
ray_rmask       Yes     No      No
ray_dbound      Yes     No      No
ray_bounce      Yes     No      No
ray_phantom     Yes     No      No
ray_shadingrate Yes     No      No
ray_shadow      No      Yes     No
ray_smask       No      Yes     No
ray_lcomponent  No      Yes     No

Commands that describe the camera and projection are listed below. In mantra, the camera is always defined so that it is located at the origin looking down the positive Z axis (i.e. objects further away have a larger Z value). All objects should be transformed so that their position is relative to the camera.

  • ray_aspect
  • ray_clip
  • ray_crop
  • ray_curvature
  • ray_dof
  • ray_even
  • ray_odd
  • ray_picture
  • ray_projection
  • ray_jitter
  • ray_sample
  • ray_raysample
  • ray_resolution
  • ray_window
  • ray_zoom

Commands that create objects for rendering are as follows:

  • ray_detail
  • ray_object
  • ray_light
  • ray_atmosphere

Commands that control the Filtering and Quantization for the output image are as follows:

  • ray_filter
  • ray_dither
  • ray_gamma
  • ray_transfer
  • ray_whitepoint

Commands used for general control of the renderer are as follows:

  • ray_alfred
  • ray_bucketsize
  • ray_cmdopt
  • ray_copmap
  • ray_octsplits
  • ray_quit
  • ray_raytrace
  • ray_render
  • ray_reset
  • ray_texcache
  • ray_time
  • ray_unlink
  • ray_verbose
  • ray_version

When Houdini generates an IFD, it typically defines all details to be used before any frame definitions. These geometry definitions are persistent for all images rendered by the IFD (i.e. between frames, Houdini will not clear geometry definitions with the ray_reset command). For each frame, Houdini defines the camera and image options. After the frame is defined, the light sources, atmosphere and geometry instances are added (in that order).

The IFD doesn't have to be structured with the camera/image definitions before the lights and geometry. However, lights may have to be defined before geometry objects (due to light mask definitions).

Sample IFD 


ray_version VEX4  # Specify the target render version 

# Define some geometry named "geo".  It is smooth shaded.
ray_detail -s geo $HH/geo/defcam.bgeo

#Define the camera and output image
ray_picture ip          # Set the output image name
ray_resolution 256 256  # Set the output resolution
ray_zoom 1              # Set the field of view
ray_clip .01 100        # Set near/far clipping planes

# Now, instance the geometry 5 times.  We can use the standard
# hscript expression evaluation and variable expansion to position
# the objects.
for i = 0 to 4
  ray_object object$i geo   # Define an instance 

   # Transform the instance
   set x = `.2 * ($i - 2)`
   ray_transform 1 0 0 0  0 1 0 0  0 0 1 0  $x $x 2.5 1

   # Apply a surface shader to the instance
   ray_shader constant clr `rand($i)` `rand($i+.1)` `rand($i+.2)`
end

# Tell mantra to render the scene
ray_raytrace

# Quit mantra
ray_quit
Retrieved from "http://odforce.net/wiki/index.php/IFDFormatDocument"
© 2009 od[force].net | advertise