Binding Command Line Geometry Converters

Overview

In the houdini distribution under $HFS/houdini is the file GEOio.json. This is parsed by Houdini to find applications to translate between Houdini geometry files and alien formats.

When any of the standard Houdini methods of reading or writing geometry files are triggered, such as in a File SOP or Geometry ROP, these applications will be searched. If there's matched, the specified shell command will be executed.

The schema for this file can be found in the file GEOio.json.schema, though unknown properties are silently skipped.

Top Level Object

The file is defined by a JSON object. The expected properties in the JSON object are:

• "translators": required
  The translators property defines an array of translator applications which convert between Houdini geometry and an alien format.
• "final": optional, default=false
  The optional "final" boolean object will determine whether further GEOio.json files will be processed. If set to true, no further configuration files in the path will be processed. If "false", the remainder of the Houdini search path will be scanned and additional translators will be added (but will not override translators already defined).

Translator Definition

Each item in the translator array defines an application which is used to translate between Houdini geometry and an alien format. Each translator is defined by a JSON object which expects the properties:

• "extensions": required
  The value for this property can be either a single string or an array of strings. For example ".dxf" or [".lw",".lwo"]
• "magic" : optional
  This should either be a single integer or an array of integers. When matching a file based on extensions doesn't work, the geometry library will try to check based on magic numbers. The library will read the first 4 bytes as a 32-bit unsigned integer. If the magic number matches, then the translator program will be invoked. This is for importing only.
• "convert": optional
  This defines a command to run to convert between formats. The value for the property should either be a single string defining the convert command or an object defining the command and options.
  Two types of expansion are done on the command. The string "%(load)s" will be replaced with the source file, and the string "%(save)s" will be replaced with the destination file. The command must be able to handle both Houdini and the alien format in either "%(load)s" or "%(save)s".
  In addition, Houdini will expand environment variables on the command during load. Environment variables allow the user to control behaviour on the translator without having to customize the translator file itself. This behaviour can be disabled with the "expand" option.
• "ipipe": optional
  This is a command to convert from the alien format into Houdini geometry. Houdini will read the geometry file from the standard output of the command.
  Like convert, the value should be either a string or object.
  If this command isn't defined, the convert command will be used where "%(save)s" will expand to "stdout.bgeo".
  If the convert command isn't defined it will not be possible to read from the alien format.
• "opipe": optional
  This is a command to convert from Houdini geometry to the alien format. Houdini will write the geometry file to the standard input of the command.
  Like convert, the value should be either a string or object.
  If this command isn't defined, the convert command will be used where "%(load)s" will expand to "stdin.bgeo".
  If the convert command isn't defined it will not be possible to write to the alien format.

When the "convert", "ipipe", "opipe", or "stat" programs are specified by an object (rather than a single string), the following properties are expected in the object:

• "command": required
  The command to run. The "%(load)s" and "%(save)s" tokens will be replaced with the source or destination files. Variable expansion may also occur.
• "format": optional, default="hjson"
  Specifies one of the internal Houdini formats. The data will be sent to the application using this format rather than the default. You can see which formats are supported by running gconvert with no arguments.
• "binary": optional, default=true
  Indicates whether to send binary or ASCII data to the application.
• "expand": optional, default=true
  Indicates whether to expand environment variables on the command when parsing the JSON file.

At the current time the stat command is not used.

Tip: Setting HOUDINI_SCRIPT_DEBUG to 3 or greater will cause the list of translators to be printed to stderr when the library invokes the translator loader (such as when running "ginfo foo.obj").

Examples

The volume import/export example shows how to build a standalone command line tool to load and save geometry. To add this to the GEOio translators, create a GEOio.json in your $HOME/houdini directory.

{
    "comment" : "Local GEOio entry",
    "translators" : [
        {
            "extensions"    : ".voxel",
            "convert"       : "geo2voxel '%(load)s' '%(save)s'"
        }
    ]
}

See standalone/geo2voxel.C for the code.

Adding File Extension Support

Adding a translator in the GEOio.json table doesn't automatically add the file extension(s) to the file browser. The file browser looks for the extensions in the GEOfiles file.