Packed character format

On this page

Overview
Data containers
Assemble and extract character data
How-to
- Pack Folder SOP
- Unpack Folder SOP and Packed Folder Split SOP

This feature is still under development. The current functionality is unfinished and subject to change, and may have thin or no documentation. Please bear this in mind when using it.

Overview ¶

To support the new animation and rigging workflows for Houdini 20, the packed character format is a way to define, bundle, and organize the data that is needed to create and animate one or more characters in the viewport. The packed character format consists of geometry data that is organized in a folder structure similar to a directory structure on disk, with the data added as nested packed primitives.

In the packed character format, there are three levels of data containers - the character scene, the character, and the character element. The packed character format hierarchy can be seen in the rig tree view:

Packed character format hierarchy in the rig tree view

Character scene

The character scene is the top-level data container that contains one or more poseable characters that can interact with each other. The scene container can also contain animation and constraints that the animator interactively adds in the animate state. The scene container can be thought of as a “folder” in the packed folder structure.

Character

A character container holds a poseable KineFX character that an animator interacts with in the viewport. The character container contains all the elements that are necessary to animate the character. At a minimum, it contains a rig. The character container can be thought of as a “folder” in the packed folder structure.

Character element

A character element is a single packed geometry element that is used when animating a character. The default types are skeleton, shape, rig, and control. There is also the option for you to define your own element with a custom extension. The character element can be thought of as a “file” in the packed folder structure.

The packed character format allows you to pack different elements together, pass it around in a scene, and extract individual elements as needed.

Data containers ¶

Character scene container ¶

The character scene container is the top-level container that contains one or more characters that can interact with each other. The starting point of the scene is usually the characters that are piped into the scene. Other elements are then added to the scene as animation is performed in the animate state. These elements include animation, constraints, and a scene.graph.

Note

The elements that are added to a scene while animating (animation, constraints, scene.graph) should not be confused with the character elements that are in a character container.

Animation

When animation is performed in the animate state, channel primitives for the animation are added to the /animation directory in the scene container. Channel primitives are animation curves that are stored along with the geometry and are optimized for the animate state.

Constraints

Constraints are like mini rigs that evaluate the dependency between two controls. When constraints are created in the animate state, a graph for that constraint is added to the /constraints directory in the scene container.

scene.graph

The scene.graph is a graph that manages and defines the order that the rigs and constraints are evaluated in the animate state. It is created and stored in the scene container. The scene.graph does not create the rig; it just executes it.

The scene.graph looks for all the characters in the scene container, assembles the characters, and creates the scene. When constraints are created in the animate state, the dependencies between the controls are added to the scene.graph. The scene.graph also stores the order in which the constraints are created.

Warning

The scene.graph is essential for scenes that have dependencies between controls/rigs (these are usually constraints). If you delete the scene.graph, you will lose the constraints that you have created in your scene.

You can have multiple character scenes within a Houdini scene (.hip) file. This is useful, for example, if you want to work on different versions of a scene.

Character container ¶

The character container contains the rig and all the character elements that the rig needs to be evaluated properly. The character can contain more than one of any given type of character element. For example, there can be 3 shapes in a character container.

The operation of a character is “rig centric”, in that the rig determines the character elements that are needed based on the rig’s inputs. If a character container contains a particular character element, but that element is not piped into the rig as an input, then the element is not used. For example, there could be 10 shapes in a character container, but only 2 of them are inputs to the rig. In this case, the rig only uses the 2 shapes, but the user may wish to keep the remaining shapes in the character container for future use.

Note

The term “character container” refers to a generic container that contains a piece of rig logic and the elements referenced by the rig logic’s inputs. In practice, a character container could be a character, a prop, or an asset.

Houdini expects the name of the character container in the packed folder structure to have a .char extension. When Houdini see the .char extension, it automatically interprets the .char packed primitive as a folder. The animate state picks up on the .char extension and looks for the rig inside the .char folder (the rig is the element with a .rig extension). Based on the rig’s inputs, the animate state then pulls in the associated character elements (for example, the skeleton or shape) that are stored in the .char folder.

Character elements inside the .char character folder

Character element container ¶

A character element is a single packed geometry that is used when animating a character. The default types are:

Skeleton (.skel)

A KineFX skeleton.

Shape (.shp)

A shape that can be used as rest skin for defomations.

Rig (.rig)

A graph that modifies a skeleton and/or shape.

Control (.ctrl)

A viewport interaction tool that defines how the UI event in the viewport is being interpreted. For example, it could define a certain behavior when you, say, drag in the viewport. The control is a graph plus a set of shapes you associate with it.

There is also the option for you to define your own element with a custom extension.

Assemble and extract character data ¶

The Pack Folder, Unpack Folder, and Packed Folder Split SOPs are used to organize the character elements in a folder structure similar to a directory structure on disk.

Pack Folder

The Pack Folder SOP packs its inputs and organizes them in a folder structure. It can either create a new folder structure or pack into an existing structure.

Unpack Folder

Once data is packed into a packed folder structure using the Pack Folder SOP, we want to be able to pull out and manipulate the data. This is done using the Unpack Folder SOP. The Unpack Folder SOP takes as input a packed folder structure, and uses a search pattern to determine the data to extract. The Unpack Folder SOP has a single output that contains the extracted data.

See the Unpack Folder SOP for details on the pattern matching syntax.

Packed Folder Split

The Packed Folder Split SOP is similar to the Unpack Folder SOP, but instead of only outputting the extracted data, it splits the incoming packed folder structure into two outputs - the original packed folder structure with the extracted data removed (default setting), and the extracted data.

Note

If you want to analyze a single element in a character, you can use the Unpack Folder SOP to extract that one element. If you want to modify something on an existing character (for example, grab the current skeleton, add a joint, and pipe it back into the skeleton), you can use the Packed Folder Split SOP.

Assemble a character ¶

In this example, we assemble a character container by adding character elements to a packed folder structure. We have the following character elements - a tube geometry, a skeleton for the tube, and rig logic that performs a bone deform. (See Working with skeletons for how to create a skeleton, and APEX graphs for building a rig logic graph.) The Joint Capture Biharmonic SOP is used to create capture weights on the geometry that is deformed by the bone deform rig logic.

The 2nd input of the the Pack Folder SOP takes in multiple character elements to add to the packed folder structure. As elements are connected to the Pack Folder SOP, Name parameters are automatically created on the Pack Folder SOP in the order that the elements are connected in. The Name parameters are automatically populated with the names of the input nodes. In this example, we have:

1st input: Name: create_capture_weights
2nd input: Name: create_capture_weights
3rd input: Name: bonedeform_rig

The Type parameters on the Pack Folder SOP are not populated, because the input nodes are not named with extensions.

To better indicate what the inputs are, we can rename the character elements and their extensions in the packed folder structure by updating the following parameters in the Pack Folder SOP:

1st input: Name: base, Type: shp
2nd input: Name: base, Type: skel
3rd input: Name: base, Type rig

Note

The character element names referenced by the rig graph inputs must match the character element names in the packed folder structure. This is so that the rig knows which character elements to pick up and use.

The image below shows the graph inputs of the bonedeform_rig node from our example. You can rename the graph input ports to match the packed folder structure by MMB clicking the port names. See APEX graphs for more information on building and running graphs.

Character elements referenced by the rig inputs

View the packed folder structure ¶

You can view the contents of the packed folder structure in two ways - using the rig tree view and the geometry spreadsheet. The rig tree view shows the entire hierarchy of the packed folder structure, whereas the geometry spreadsheet only shows the top level of the packed folder structure.

Rig tree view

Select the Pack Folder SOP in the network editor.
At the top of the pane where you want to open the rig tree view, click the New Tab icon, and select New Pane Tab Type ▸ Animation ▸ Rig Tree.
In the rig tree view, beside the node name (in our case, create_character), set the drop-down box to the output.
Set Type to Packed Folders.
You can view the packed folder structure in two ways:
- Set Hierarchy to Topology to view the packed folder structure as a tree view.
- Set Hierarchy to Flat List to view the packed folder structure as a flat list.

The following packed folder hierarchy will be displayed:

/
-- base.shp
-- base.skel
-- base.rig

Geometry spreadsheet

Select the Pack Folder SOP in the network editor.
At the top of the pane where you want to open the geometry spreadsheet, click the New Tab icon, and select New Pane Tab Type ▸ Inspectors ▸ Geometry Spreadsheet.
Click Primitives on the top toolbar of the geometry speadsheet. The character elements (base.shp, base.skel, base.rig) will be listed.

Assemble a character scene ¶

In this example, we assemble a character scene by using APEX Scene Add Character SOPs to add each character to the scene container.

On each of the APEX Scene Add Character SOPs, specify a name for the character in the Character Name parameter. See the animation workflow for more information on assembling a scene for animation.

In the rig tree view, we have the following packed folder hierarchy for the scene container:

/
-- character1.char/
    -- base1.shp
    -- base1.skel
    -- base1.rig

-- character2.char/
    -- base2.shp
    -- base2.skel
    -- base2.rig

To pose and animate characters in the animate state:

Pipe the scene into an APEX Scene Animate SOP.
Select and display the APEX Scene Animate SOP.
Click Animate on the left toolbar or press Enter in the viewport.

Perform animation on the APEX Scene Animate SOP

Extract data from a packed folder structure ¶

You can use the Unpack Folder SOP or Packed Folder Split SOP to extract data from a packed folder structure. In this example, we use the Unpack Folder SOP to extract a rig from the scene.

In the Unpack Folder SOP, set Extract Pattern to /character1.char/base.rig to extract the rig from the character1 container. See the Unpack Folder SOP for details on the pattern matching syntax used in the search pattern.

Warning

If the search pattern matches multiple rigs in the scene (for example, something like /**/*.rig), you could end up extracting multiple rigs that are then merged into one unpacked geometry. The APEX network view may display a graph that looks valid, but the graph may exhibit unexpected behavior.

Note

On the Unpack Folder SOP, if Unpack Contents is turned on, the rig that is extracted is unpacked, which gives you the rig graph geometry. You can view this extracted rig graph in the APEX network view.

If Unpack Contents is turned off, the rig that is extracted is a packed primitive instead of a graph geometry. The APEX network view will not display the extracted rig packed primitive.

The rig tree view only shows data that is packed in the packed folder structure. If Unpack Contents is turned on, the extracted data is unpacked geometry, and the rig tree view will not display any data.

To view the extracted packed primitives (Unpack Contents is turned off) in the rig tree view:

In the rig tree view, beside the node name (in our case, extract_rig), set the drop-down box to the output.
Set Type to Packed Folders.

The data that is extracted is displayed as follows:

/
-- base1.rig

How-to ¶

To... Do this

To...	Do this
View the packed folder structure	You can view the contents of the packed folder structure in two ways - using the rig tree view and the geometry spreadsheet. The rig tree view shows the entire hierarchy of the packed folder structure, whereas the geometry spreadsheet only shows the top level of the packed folder structure. Rig tree view At the top of the pane where you want to open the rig tree view, click the New Tab icon, and select New Pane Tab Type ▸ Animation ▸ Rig Tree. In the rig tree view, beside the node name, set the drop-down box to the output. Set Type to Packed Folders. You can view the packed folder structure in two ways: Set Hierarchy to Topology to view the packed folder structure as a tree view. Set Hierarchy to Flat List to view the packed folder structure as a flat list. Geometry spreadsheet At the top of the pane where you want to open the geometry spreadsheet, click the New Tab icon, and select New Pane Tab Type ▸ Inspectors ▸ Geometry Spreadsheet. Click Primitives on the top toolbar of the geometry speadsheet. For the Packed Folder Split SOP, you can select from the drop-down menu beside the node name to view either the Packed Folders or the Extracted data.
View the primitives on the geometry spreadsheet	On the geometry spreadsheet, you can view: The packed primitives added to the packed folder structure by the Pack Folder SOP. The packed primitives being passed through the Packed Folder Split SOP. The packed or unpacked primitives extracted by the Unpack Folder and Packed Folder Split SOPs. The packed or unpacked primitives of any input nodes. At the top of the pane where you want to open the geometry spreadsheet, click the New Tab icon, and select New Pane Tab Type ▸ Inspectors ▸ Geometry Spreadsheet. Click Primitives on the top toolbar of the geometry speadsheet. Select a Pack Folder SOP, Unpack Folder SOP, Packed Folder Split SOP, or an input node to view the primitives on those nodes. Note The geometry spreadsheet only shows what is packed at the top level of the selected node, while the rig tree view shows the entire hierarchy of the packed folder structure. You can see whether the packed primitive in the packed folder structure is a folder or element using the `treatasfolder` intrinsic in the geometry spreadsheet: Select the Pack Folder, Unpack Folder, or Packed Folder Split SOP. From the Intrinsics drop-down menu on the top toolbar of the geometry speadsheet, turn on treatasfolder. Folders have a value of `1`, and elements have a value of `0`. Note If you have Unpack Contents turned on in the Unpack Folder or Packed Folder Split SOP, the data that is extracted is unpacked, so the `treatasfolder` intrinsic is not available to be selected.

View the packed folder structure

Rig tree view

At the top of the pane where you want to open the rig tree view, click the New Tab icon, and select New Pane Tab Type ▸ Animation ▸ Rig Tree.
In the rig tree view, beside the node name, set the drop-down box to the output.
Set Type to Packed Folders.
You can view the packed folder structure in two ways:
- Set Hierarchy to Topology to view the packed folder structure as a tree view.
- Set Hierarchy to Flat List to view the packed folder structure as a flat list.

Geometry spreadsheet

At the top of the pane where you want to open the geometry spreadsheet, click the New Tab icon, and select New Pane Tab Type ▸ Inspectors ▸ Geometry Spreadsheet.
Click Primitives on the top toolbar of the geometry speadsheet.
For the Packed Folder Split SOP, you can select from the drop-down menu beside the node name to view either the Packed Folders or the Extracted data.

View the primitives on the geometry spreadsheet

On the geometry spreadsheet, you can view:

The packed primitives added to the packed folder structure by the Pack Folder SOP.
The packed primitives being passed through the Packed Folder Split SOP.
The packed or unpacked primitives extracted by the Unpack Folder and Packed Folder Split SOPs.
The packed or unpacked primitives of any input nodes.

At the top of the pane where you want to open the geometry spreadsheet, click the New Tab icon, and select New Pane Tab Type ▸ Inspectors ▸ Geometry Spreadsheet.
Click Primitives on the top toolbar of the geometry speadsheet.
Select a Pack Folder SOP, Unpack Folder SOP, Packed Folder Split SOP, or an input node to view the primitives on those nodes.

Note

The geometry spreadsheet only shows what is packed at the top level of the selected node, while the rig tree view shows the entire hierarchy of the packed folder structure.

You can see whether the packed primitive in the packed folder structure is a folder or element using the treatasfolder intrinsic in the geometry spreadsheet:

Select the Pack Folder, Unpack Folder, or Packed Folder Split SOP.
From the Intrinsics drop-down menu on the top toolbar of the geometry speadsheet, turn on treatasfolder. Folders have a value of 1, and elements have a value of 0.

Note

If you have Unpack Contents turned on in the Unpack Folder or Packed Folder Split SOP, the data that is extracted is unpacked, so the treatasfolder intrinsic is not available to be selected.

Pack Folder SOP ¶

To...	Do this
Create a new packed folder structure	Don’t connect anything to the 1st input of the Pack Folder SOP. Data connected to the 2nd input will be used to create a new packed folder structure.
Add to an existing packed folder structure	Connect the existing packed folder structure to the 1st input of the Pack Folder SOP.
Add data to the packed folder structure	Connect data to the 2nd input of the Pack Folder SOP. The Name and Type parameters are automatically populated with the names and extensions detected from the inputs. You can specify relative paths in the Name parameter. For example, if Parent Folder is set to `/root`, Name is set to `obj1/test`, and Type is set to `rig`, then `/root/obj1/test.rig` is added to the packed folder structure.
Add data to a particular folder in the packed folder structure	In the Parent Folder parameter, specify the folder path to add the input data to. If the path does not exist, it will be created. or Open the rig tree view. Click the button beside the Parent Folder parameter. On the rig tree view, select the folder you want to put the items into, and click Accept. The Parent Folder parameter will be filled in with the selected folder. Note If you fill in the Parent Folder parameter with a path that does not exist, the path will be created. If you fill in the Parent Folder parameter with an element (non-folder) name, there will be an error on the Pack Folder SOP.
Use the input geometry names in the packed folder structure	Consider the example where two box geometries are connected to a Merge Packed SOP, and the Merge Packed SOP is connected to a Pack Folder SOP. When you connect data to the 2nd input of the Pack Folder SOP, the Name and Type parameters are automatically populated with the names and extensions detected from the connected inputs. In this case, Name is set to `mergepacked1`. Type is left empty, because mergepacked1 does not have an extension. The rig tree view shows that the Pack Folder SOP has added `mergepacked1` to the packed folder structure: / -- mergepacked1 If you click the action button beside the Name and Type parameters and select Names/Types From Input, the Name and Type parameters will be populated with the `__INPUT__` keyword. This indicates that the `name` attributes of the input geometry are used when adding to the packed folder structure (in this case, the `name` attributes are added by the Merge Packed SOP). The rig tree view shows that the Pack Folder SOP has added two elements to the packed folder structure - box1.shp and box2.shp. / -- box1.shp -- box2.shp Note The Name From Input option can only be used if the input geometry has a `name` attribute. You can set the `name` attribute of the input geometry using a Name SOP or Merge Packed SOP. If no `name` attribute exists, the input is not added to the packed folder structure. When using the Name SOP, set the Class parameter to Primitive.
Add data using a built-in extension	The built-in extensions .char and .ctrl are added to the packed folder structure as folders, whereas all other built-in extensions are added as elements. When adding an input as a folder: If the input has a `name` attribute, the Pack Folder SOP adds a packed folder with a single, unpacked item inside. For example, if `box.ctrl` is an input to the Pack Folder SOP, and it has a `name` attribute of `box_geometry`, the rig tree view will show the following packed folder structure: / -- box.ctrl (packed folder input) -- box_geometry (unpacked element) If the input does not have a `name` attribute, the Pack Folder SOP adds a packed folder with unnamed data to the packed folder structure. For example, if `box.ctrl` is added to the Pack Folder SOP as an input, the rig tree view will show the following packed folder structure (the unnamed elements will not be shown): / -- box.ctrl (packed folder input) If you input this packed folder structure to an Unpack Folder or Packed Folder Split SOP, and turn on the Unpack Contents parameter, the data extracted will be the original unnamed box primitives. Note You can see whether data in the packed folder structure is a folder or element by turning on the `treatasfolder` intrinsic on the geometry spreadsheet.
Add data using a custom extension	Specify a custom extension in the Type parameter. The icon menu beside the action button gives the option of adding the input as an element or a folder.
Specify how to handle new data that has the same name as existing data in the folder structure	Choose between three options in the Replace Method parameter: Add and Replace New items are added, and existing items are replaced. Add and Keep Existing New items are added, and existing items are kept the same. Replace New items are not added, and existing items are replaced.
Reset the names/types of the packed objects to those of the input nodes	Click the Reload Names button.
Ignore inputs with no geometry	Select the Ignore Empty Inputs option.
Only pack data that is unpacked (don’t pack data that is already packed)	Turn on Pack Output. Turn on Only Pack Unpacked. See the Pack Folder SOP for more information on these parameters.

Unpack Folder SOP and Packed Folder Split SOP ¶

To...	Do this
View the extracted data	The extracted data can be viewed in both the rig tree view and geometry spreadsheet. In the rig tree view: Beside the node name, set the drop-down box to the extracted output. Set Type to Packed Folders. In the geometry spreadsheet: Click Primitives on the top toolbar. For the Packed Folder Split SOP, select Extracted from the drop-down menu beside the node name.
Extract data from a particular path	In the Extract Pattern parameter, put the path to the file you want to extract, for example, `/root/object1/test1.rig`.
Extract all data with a specific name	For example, to extract all data named box2.shp, put `box2.shp` in the Extract Pattern parameter. The Unpack Folder and Packed Folder Split SOPs goes through every folder in the packed folder structure and extracts all elements named box2.shp.
Extract all data with a specific extension	For example, to extract all .shp files, put `.shp` in the Extract Pattern* parameter.
Extract data based on an attribute or group name	In the Extract Pattern parameter, enclose the search pattern in “`{}`”. The search pattern uses the same group syntax as the Group parameter on other SOPs. For example, `{@name=test3.rig @index=2-3}` extracts test3.rig, as well as all data with an `index` attribute of 2 or 3. Note Data is only extracted if all of its primitives match the search pattern. For example, if a data’s primitives have indices from 0-5, then a search pattern of `{@index=2-3}` will not extract the data, because some of its indices are outside the search pattern range. You can also combine path and attribute/group search patterns. For example, `object3/ - {@index>=2}` extracts all data in folders that begin with `object3`, but not data with indices greater than or equal to 2. See the Extract Pattern parameter for the pattern matching syntax, including the use of `&`, `+`, and `-` to combine multiple search patterns.
Unpack the extracted data	Turn on the Unpack Contents parameter to unpack the extracted data. If the data has been packed multiple times (there are multiple levels of packing), turning on Unpack Contents only unpacks the top level of the extracted data.
Keep the extracted data in the Packed Folders output (for Packed Folder Split)	Turn on the Extract Only parameter. The data is only extracted and not removed from the Packed Folders output.
Output the non-extracted data (for Unpack Folder)	Turn on Invert.
Reverse the order of the outputs (for Packed Folder Split)	Turn on Invert Selection.

Packed character format

Overview ¶

Data containers ¶

Character scene container ¶

Character container ¶

Character element container ¶

Assemble and extract character data ¶

Assemble a character ¶

View the packed folder structure ¶

Assemble a character scene ¶

Extract data from a packed folder structure ¶

How-to ¶

Pack Folder SOP ¶

Unpack Folder SOP and Packed Folder Split SOP ¶

KineFX

Preparing rig inputs ¶

Procedural Rigging ¶

Deformation ¶

Animation ¶

Appendix ¶

Animation Retargeting ¶

KineFX 19.5 functionality ¶

Compatibility ¶

Panes ¶