Packed character format

On this page

Data containers
Assemble data into a packed folder structure
- Add character elements
  - View the packed folder structure
- Assemble an animation scene
Extract data from a packed folder structure
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.

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 animation scene, the characters, and the character elements. The packed character format hierarchy can be seen in the rig tree view:

Packed character format hierarchy in the rig tree view

Animation scene

An animation 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 can interact 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. You can also define your own elements with custom extensions. 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.

The Pack Folder, Unpack Folder, and Packed Folder Split SOPs are used to organize, assemble, and extract character elements in the packed character format:

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 assembled 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 the APEX path pattern syntax to search for the data to extract. The Unpack Folder SOP has a single output that contains the extracted data.

Packed Folder Split

The Packed Folder Split SOP is similar to the Unpack Folder SOP, but instead of outputting only 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.

Data containers ¶

Animation scene container ¶

The animation 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 the constraint is added to the /constraints directory in the scene container.

scene.graph

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

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 animation 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, prop, or asset.

Houdini expects the name of the character container to have a .char extension. The .char packed primitive is automatically interpreted as a folder in the packed folder structure. The animate state looks for the rig (.rig extension) inside the .char folder, and based on the rig’s inputs, 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 a rest skin for deformations.

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.

You can also define your own elements with custom extensions.

Assemble data into a packed folder structure ¶

The Pack Folder SOP is used to assemble the input character elements into the packed character format. It can either create a new folder structure or pack into an existing structure.

Add character elements ¶

In this example, we add the 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. The Joint Capture Biharmonic SOP is used to create capture weights on the geometry:

The 2nd input of the the Pack Folder SOP takes in multiple character elements that are added to the packed folder structure. As elements are connected to the Pack Folder SOP, Name parameters are automatically created on the SOP in the order of the input connections. 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: 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 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 rig node from our example above. 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.
To open the rig tree view, click the New Tab icon at the top of a pane and select New Pane Tab Type ▸ Animation ▸ Rig Tree.
In the rig tree view, beside the node name (in our case, assemble_character_elements), 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.rig
-- Base.shp
-- Base.skel
```

Geometry spreadsheet

Select the Pack Folder SOP in the network editor.
To open the geometry spreadsheet, click the New Tab icon at the top of a pane 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, and Base.rig) will be listed.

Assemble an animation scene ¶

In this example, we assemble a scene for animation using an APEX Scene Add Character SOP for each character. The APEX Scene Add Character SOP adds a character’s elements to a character (.char) folder, and then adds the character to an animation scene:

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

After renaming the character elements in the Pack Folder SOPs, we have the following packed folder hierarchy in the scene container:

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

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

To pose and animate characters in the animate state:

Pipe the scene into an APEX Scene Animate SOP:

Perform animation on the APEX Scene Animate SOP
Select and display the APEX Scene Animate SOP.
Click Animate on the left toolbar.

Extract data from a packed folder structure ¶

The Unpack Folder and Packed Folder Split SOPs are used to extract character elements from a packed folder structure. Both SOPs take as input a packed folder structure, and uses the APEX path pattern syntax to search for the data to extract. The Unpack Folder SOP has a single output that contains the extracted data, whereas the Packed Folder Split SOP 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.

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.

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 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 this packed primitive rig.

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 in the rig tree view:

On the Unpack Folder SOP, turn off Unpack Contents.
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:
```
/
-- Base.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 To open the rig tree view, click the New Tab icon at the top of a pane 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 To open the geometry spreadsheet, click the New Tab icon at the top of a pane 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 Extracted data.
View the primitives in the geometry spreadsheet	In 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. To open the geometry spreadsheet, click the New Tab icon at the top of a pane 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

To open the rig tree view, click the New Tab icon at the top of a pane 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

To open the geometry spreadsheet, click the New Tab icon at the top of a pane 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 Extracted data.

View the primitives in the geometry spreadsheet

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

To open the geometry spreadsheet, click the New Tab icon at the top of a pane 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 Click the button beside the Parent Folder parameter. In the rig tree view, select the folder you want to put the items into and click Accept. The Parent Folder parameter will be populated 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 the `mergepacked1` node 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 or Type parameter and select Names/Types From Input, the Name/Type parameter 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 the `name` attribute `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 the data in a packed folder structure is a folder or element by turning on the `treatasfolder` intrinsic in the geometry spreadsheet.
Add data using a custom extension	Specify a custom extension in the Type parameter. The menu gives the option of adding the input as an element () or 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	Turn on 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 go through every folder in the packed folder structure and extract 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 the data in folders that begin with `object3`, but not data with indices greater than or equal to 2. See APEX path pattern 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

Data containers ¶

Animation scene container ¶

Character container ¶

Character element container ¶

Assemble data into a packed folder structure ¶

Add character elements ¶

View the packed folder structure ¶

Assemble an animation scene ¶

Extract data from a packed folder structure ¶

How-to ¶

Pack Folder SOP ¶

Unpack Folder SOP and Packed Folder Split SOP ¶

KineFX

Overview ¶

Preparing character elements ¶

Rigging with APEX graphs ¶

Building rig graphs with APEX Script ¶

Rigging with rig components ¶

Animating in the viewport ¶

SOP-based animation ¶

Deformation ¶

Animation retargeting ¶

Pre-H20 ¶

Panes ¶

Appendix ¶