Massrib is a command-line tool for manipulating the rib files produced by Massive.

Note:  Massrib is no longer needed to render Massive scenes with Air on Windows now that Massive and the Massive procedural primitive run under Windows.

Overview

Massive uses a procedural primitive to generate the members of a crowd at render-time, which is very efficient but not easy to customize.  The main function of massrib is to convert the Massive procedural calls to a plain binary or text rib file.  The resulting "flat" rib file can be rendered without access to the Massive scene files or Massive procedural.  A flat rib is also amenable to further postprocessing, since it is just a plain rib file.

There are several disadvantages to using a flat rib.  First, the flat rib files themselves can be rather large.  Second, the procedural method of crowd-generation employed by Massive allows AIR to render huge scenes very efficiently, since each agent is generated only as (and if) it is needed.  If an agent does not need to be ray-traced, AIR can also dispose of an agent as soon as it has been rasterized by the scanline renderer.  When rendering a flat rib, AIR will load all agents which will consume more memory.  Even with a flat RIB, AIR should be able to render many hundreds to thousands of agents before running out of memory.

Usage

massrib render.0000.rib

Given a source rib name, massrib produces a "flat" rib with the same name in an output directory.  By default the output directory is a massrib subdirectory of the current directory, which massrib will create if necessary.  An alternate output directory can be specified using the -outdir option:

massrib -outdir /usr/local/tmp/flat render.0000.rib

The simplest way to use massrib is to convert the main scene rib generated by Massive.  The resulting flat rib will include the agents and terrain in a single file.  You can also convert only the agent archive, producing an archive with just the agents for inclusion in a scene generated in another application.  Multiple files can be processed using simple wildcards.  E.g.,

massrib render.*.rib

Setting Massive Procedural Options

The Massive scene file includes an additional call to the procedural primitive that sets certain options such as motion blur and pass type for subsequent agent calls to the procedural primitive.  In the current Massive version the call to set procedural options appears after the calls to create the agents in the rib stream, which means that massrib would generate the agents before the options have been set.  To work around this problem, massrib includes a -massopt command line parameter that can be used to provide option information which massrib will use to initialize the procedural primitive.

To find the Massive procedural options, look at the bottom of the main scene rib for a line that looks like:

Procedural "RunProgram" ["run_program.exe" "options motion_blur off render_pass beauty air "] [-2250.06 2249.94 -262.813 281.777 -2250.36 2249.64]

The second string enclosed in quotes contains the options.  Pass that entire string (including the quotes) to massrib with -massopt:

massrib -massopt "options motion_blur off render_pass beauty air " render.0000.rib

The options should be the same for every frame in a sequence.  By default massrib will look for the procedural primitive in /usr/local/massive/bin.  If Massive is installed in a different location, include a -procpath option prior to the -massopt option with the path to the Massive procedural.

Additional Command Options

-ascii

By default massrib produces a rib file in binary format for compactness.  Use -ascii to generate a plain text rib file.

-mapdir olddir=newdir

This option allows path and file references in the source scene to be remapped.  For example, with the following massrib invocation:

massrib -mapdir /usr/local/texture=i:/texture

a reference in the source rib file to /usr/local/texture/shirt.tif would become
i:/texture/shirt.tif in the output rib file.  Useful for changing texture references for rendering under Windows.

-optrib ribfilename

This option inserts additional rib commands from the specified file into the output stream just prior to the WorldBegin statement  Useful for adding custom options and attributes to a scene.

Start massrib with no arguments to display a list of command line options.

See Also

The new RIB filtering mechanism in Air 6 offers an alternate means of customizing the rib stream produced by the Massive procedural primitive.