Houdini 13.0 Nodes

interface version 2

Marks a point in a SOP network where intermediate (or expensive) results can be saved to disk and re-used.

If you have complex SOP networks with many nodes (such as large-scale RBD or particle simulations, etc.), you probably want to break down your network to a few logical units. A Waypoint SOP can represent the end of such a logical unit, with the additional feature of being able to store it on disk (so it can be reused instead of recalculated).

Note

Waypointing is (conceptually) not caching, although the underlining mechanism is similar (and obviously the SOP node can be used as a cache). It’s more akin to 'baking' than caching.

Conceptual differences between waypointing and caching

  • Waypoint: a separator between large logical units

    In really complex networks, the entire network consists of usually two or more large logical units. A waypoint marks the end of such a unit ('compartment').

  • Manual update: As workflow

    When the user finished working on (or modifying) a large logical block of SOP nodes, she marks it by 'rendering' the related waypoint (possibly some downstream waypoints, too). Although this has to be done manually, this level of caretaking always has to happen in practice (it’s also a good opportunity to compare with an earlier on-disk version, etc.)

  • Manual update: Breaks procedural behaviour

    Caching is (supposed to be) automatic, waypointing is not.

    A consequence of manual updating is that it is easy for the geometry on disk to get out of sync with the state of the SOP network. This can be less of a problem if the waypoint represents the end results of a large logical SOP block (as mentioned above).

    On the other hand, a SOP network littered with Waypoint nodes do turn into a nightmare quickly. So...

Warning

This SOP introduces additional (manual) maintenance burdens to your SOP network – as soon as you start using waypoints, you’ll have to ensure that the geometry on disk matches the current state of the upstream network. This can be a source for many mistakes. Use as few instances of this node as possible.

Useful features

Takes

Takes allow to work with lower-quality settings (if possible) and only calculate with higher settings when writing the results to disk (e.g. when baking ambient occlusion to per-point colors, the sampling quality can be boosted for the disk version only).

Variants

The writing/reading of multiple variants of the same input is supported (see the Output Variant and Variant Names parameters below). One practical application is when used together with a Wedge output driver (ROP).

Tip

To quickly build ROP networks of Waypoints, create a ROP network, then use one of the following buttons in the Tools tab:

  • Tools->Create linked Fetch ROP

  • Tools->Create Fetch + Wedge ROP

(Make sure you set the Target ROP Network parameter on all your Waypoints.)

Then you can build the ROP network by connecting the generated nodes in the proper order. By rendering this ROP network, all your Waypoints will be updated properly.

Substep Support

Substepping is used if more than one evaulated geometry is to be saved for each frame. Useful applications:

  • The waypointed results are to be retimed (especially slow-motion)

  • Multi-segmented motion blur is desired for rendering

Tip

The easiest way of setting up substep output is to press Tools->Substep Output Setup and choose a preset. This sets up all related parameters to working defaults. (The Current Substeps field shows the number of substeps currently set up.)

For properly working substepping the following needs to be set up:

  • The filename extension should support fractional frame values (see provided presets)

  • The frame range increment should be set to the appropriate value (which is 1.0/substeps – also, there are presets provided)

  • Frame range clamping should be enabled in the Reader tab (this provides the proper fractional frame values for reading back a substepped sequence)

Note

Waypoints don’t provide any interpolation of geometry data. Use a TimeBlend qL SOP or equivalent (TimeBlend qL also supports substeps).

Also, certain numerical inaccuracies might occur when using small frame increments (this is due to the floating-point represetation).

Recommended variables

There is a special output directory preset called $HIPCACHE/$HIPVARIANT setup.

This preset uses two user-defined variables for specifying the output path:

variable

recommended default value

$HIPCACHE

$HIP/tmp--sim – A subfolder in the scene file directory.

Having this variable allows relocating the cache folder to another path if necessary (e.g. to a faster/local disk, etc.)

$HIPVARIANT

$HIPNAME:r – Hip file name, without extension.

This still uses the hip file name in the output path, but it allows saving a differently named hip file if necessary.

Note

These variables don’t exist by default and need to be set up manually.

To read more about setting up variables, see the Environment qL OBJ help page. (It is similar to Edit->Aliases and Variables... – except that it can store paths with other variables un-expanded.)

Parameters

Pass Through

If turned on, the Waypoint does nothing (behaves like a plain Switch node). This is 'On' by default and needed to be turned off explicitly once the user performed a write-to-disk operation.

Waypoint State

Main node state. Whenever it’s changed, the node color also gets updated to give more distinct visual feedback.

Pass Through (Disabled)

An inactive waypoint. It just passes through any input geometry as it is.

Active (Read from Disk)

An active waypoint that reads geometry from disk and feeds it to its output.

Start/End/Inc

The frame range to be used.

Note

Substepping (multiple files per frame) is fully supported by using fractional values for the Increment parameter. Use the preset popup (at the right) to choose a reasonable default (but most importantly see the Substepping section above on how to set it up easily).

File Name (tab)

Settings for the path/name of the output file(s).

The folder, name and extension parts are each represented by a parameter. This makes setting them up quick and easy (it’s usually just clicking on one of the preset menu items).

They also come with very reasonable default values (basically you're just have to give the Waypoint a meaningful name and that’s it).

Output Dir. Functions
Create Output Directory

Pressing this button will create the directory set up in the File Name section. Note that this also happens automatically before each geometry write, so there’s usually no need to do this manually.

Open in File Manager

Open the output directory in the operating system’s native file manager (right now it’s linux-only and launches the Gnome nautilus application).

Delete Directory

Pressing this button will delete the entire output folder with all contents. Useful for getting rid of large amounts of cached geometry (but make sure the folder doesn’t contain anything else important).

Output Directory

The folder to store the output file(s) in. If it doesn’t exist, it will be created before writing. By default it’s a subfolder with the name of the Waypoint node.

Name

The output file name. (See the pop-down menu for the most common settings, including variant-by-number and variant-by-name, see below.)

Extension

Output file extension (with file numbering for sequences). See the pop-down menu for the most regular values.

Tip

The .gz suffix indicates file compression; .bhclassic is the “old” H11 bgeo format, compatible with other applications such as PartIO. Make sure a proper substep preset is chosen if substepping is to be used.

Output Variant

This parameter allows to include a variant (version) in the output file name (using the appropriate Name presets).

It lets the user save a new version instead of overwriting the previous one (just by incrementing this parameter), or to use a Wedge ROP to generate multiple versions from a ROP network.

Variant Names

A list of names associated with variant indices (space-separated – first is variant #0, second is variant #1, and so on).

To use named variants, select the appropriate naming preset from the Name pop-down menu.

Variant Name (feedback)

This is a read-only parameter that returns the variant name specified by the variant number. (Try pressing MMB on the parameter label, then pull on the variant slider to see the names displayed).

This is a “feedback” parameter for display purposes, but it can also be used in expressions (e.g. in the output file name, see above).

Full Path/Name

This parameter contains the final pathname that is passed to both the geometry writer and reader.

Although it can be edited, it's recommended to keep the default expression as it is, and use the parameters above to build the output file name.

This parameter is intended to be used mostly as feedback. Press MMB on the parameter label to toggle its display to show the current path string.

On Cleanup

An action this node should perform when it needs to clean up after itself.

Do nothing

Do nothing.

Ask user

If this node is being deleted, it displays a dialog if it should delete its output directory from disk (to avoid wasting disk space with obsolete data).

Delete Output Directory

This will unconditionally delete the output directory – even on application exit. Although care must be taken, this behaviour has its uses (such as waypointed partial results automatically cleaning up after themselves.)

Compression (tab)

Options to make the geometry data more compact.

Tip

These are applied in Pass-Through mode, allowing the differences to be inspected by the user.

Delete Attributes

A list of attribute names to delete before writing.

Points-Only for Consecutive Frames

If enabled, only the first frame will contain the complete geometry when writing sequences. The other frames will store point data only (even that is stripped down to position and velocity by default – the idea to reduce disk consumption, I/O and geometry construction time.)

Works best with “regular” high-res geometry (i.e. lots of primitives). Do not use it for particles (or objects with changing topology).

Remove Attrs (cons.)

Which attributes to remove from the 'points-only' files. The default is to remove all but v (velocity). Groups are always removed.

Number of Casts

A list of attribute data precision conversions.

Writer (tab)

Geometry writing settings (see also Geometry ROP).

Output File

The path and filename of the geometry file. By default the geometry name is built from the Waypoint SOP name and the Input Select index.

Render with Take

The upstream network will be evaluated using the specified Take.

Progress

Type of progress indication to use during the write process.

Save HIP File Before Write/Render

This will do a File->Save operation as the very first step. It will only save the scene if there are changes since the last save.

Initialize Simulation OPs

Force all simulation OPs to be reset. This includes DOP Networks, POP SOPs, and other OPs that cache their results.

This is the safest way to render out a simulation, because it starts the simulation from scratch and discards any partial simulations you might have done with different parameters.

Nodes like the Cache SOP are not affected by this switch (but see below).

Clear Cache OP(s)

This parameter supports explicit resetting of Cache-like SOP nodes before waypointing.

Although it has to be set up manually, it provides a mechanism to flush memory-caching based SOP(s) before waypointing, to ensure up-to-date results.

Before rendering it goes through all the given nodes, and tries to press the appropriate equivalent of a “reset cache” button.

The following button names are supported: clear, resimulate. (this covers nodes like Cache, Trail, Solver, DOP Network.) Multiple nodes and wildcards (*) can be specified.

The pop-down menu provides a few basic presets to work from.

PerfMon Output

If enabled, the Performance Monitor will be recording during the rendering process, and the resulting data will be saved to the file specified.

Clear Comment Log

The comment field of the node is used as a simple message logging area (mostly logging rendering start/finish times). This button clears the comment field.

Reader (tab)

Geometry reading settings (geometry file name is specified in the Output File field above – see also File SOP).

Reload Geometry

Pressing this button will (re)read the geometry file from disk.

Clamp Range

This clamps the geo reader’s frame range (by default to the written range). It’s recommended to leave it enabled, especially for substepped setups.

Frame #

The expression for determining the current frame if Clamp Range is enabled. By default it performs frame range clamping and fractional rounding for substeps.

Tools (tab)
Writer OP Path

This field’s expression provides the full path to the Waypoint’s internal render output OP. It can be useful if this exact path is needed (when rendering from a command shell, for example).

To get the path, press MMB on the label to see the expression results, then right-click and choose Copy Parameter to copy the path to the clipboard.

Supstep Output Presets

Quick and easy output of substepped file sequences.

By picking a preset, all related parameters will be set up (filename extension, frame range increment, clamp/rounding in reader).

After such a preset is applied, the number of substeps can be changed by adjusting the Writer->Start/End/Inc.->Increment parameter (there’s a preset popup menu provided there as well).

An additional Current Substeps indicator is also displayed here if multiple substeps are being used.

Build File SOP (Loader)

Creates a File SOP that is set up to read the file(s) written by the current waypoint node (including variants).

Build FileMerge SOP

Creates a File Merge SOP that is set up to read the file(s) written by the current waypoint node (including variants).

Tip

This node is ideal for loading geometry consisting of multiple files for a frame (such as particles generated with a “wedged-seeded” workflow).

ROP Node(s)

Functions for building output (ROP) networks for rendering of...

  • several Waypoints in specified, fixed order

  • multiple iterations of a single Waypoint node (wedging)

...or combinations of the above.

Target ROP Network

Path to the output network container to create nodes to. If it doesn’t exist, it will be created.

Create Fetch / Wedge / Fetch+Wedge ROP

Creates a Fetch, a Wedge, or both to render this waypoint (in the specified ROP network).

Create Fetch + Multiple Wedges

Same as the third combo above, but instead of a single Wedge ROP, it creates copies of the same Wedge ROP for each value in the Wedge Range (see below).

This results in a Wedge node for each variant, so every single variant can be rendered by calling the corresponding Wedge. This might be convenient for running multiple wedges simultaneously on the same machine in batch mode, for example.

Wedge Variant Parm

Name of the Waypoint SOP parameter that should be “wedged” (changed for each wedge). The default setting is to work with the Waypoint’s variant parameter.

Wedge Range

The range to set up on wedge node(s). The wedge(s) will go through this numeric range and render the Waypoint for each value.

To Do

  • Shouldn’t be time-dependent if a single frame is cached

  • Make sure it works embedded in another asset (although generally it’s not a recommended thing). Most problems would be when it tries to changes itself (color, etc).

Release Notes

interface version 2 —

2014-10-13

  • Added “Save HIP File Before Render” switch

  • Better error handling (more verbose messages, etc)

  • In batch mode each Waypoint now prints out its RENDER node path

  • Other minor fixes

2014-09-11

  • Fixed typo that broke Fetch/Wedge creation tools

2014-07-12

  • Added “Progress” parameter (stderr progress indicator)

  • Minor ROP/fetch generation-related c.c.-s

2014-06-04

  • Folder “Open in File Manager...” should now work on all platforms (windows, mac)

2014-05-17

  • Removed (hidden) Report Network Use toggle

  • Added Compression tab (a la FileCache SOP)

2014-04-05

  • Added toolid/toolcount user data creation for newly created nodes.

2014-03-14

  • Consolidated descriptive parm (extra info shown in network view)

  • Added $HIPCACHE/$HIPVARIANT output dir preset

2014-02-16

  • More Output Directory presets

2013-09-27

  • Default extension is now uncompressed bgeo sequence

  • Added support for sub-frame waypointing (multiple files per frame). See the sub-frame support paragraph.

2013-09-12

Clear Cache OPs now supports the Reload button on File SOPs.

2013-08-24

Added a read-only field Render OP Path.

2013-07-31

Waypoints are now created with the appropriate color reflecting their state (even if there’s a permanent default preset with a non-default passthru value).

Limitation: node color doesn’t (yet) change when applying a preset.

2013-06-16

Removed UI annoyance when deleting a waypoint: now it asks to delete the related directory if it actually exists.

2013-05-25

Important: Applied a few modifications so Waypoints could be used within assets without problems (yet to be tested – post-render auto-reloading of geometry can be a problem). For now it’s safest to specify waypoints in assets as editable nodes.

  • Additional minor fixes (cleanup-related)

  • Internal geometry reload is flagged to be triggered at each post-frame, so it will refresh even if a sequence is aborted

  • New: added support for explicitly clear cache-like SOPs with 'Initialize Simulation OPs' toggle in Writer

2013-05-24

  • Added “On Cleanup” option (allows auto-deletion of output dir on quit)

  • Some UI cosmetics

2013-05-05

  • Improved descriptive parm.

  • Fixed important issue: rendering a waypoint will invoke an automatic file reload.

    (The lack of auto-reload was especially annoying for chained Waypoints rendered from a corresponding chained ROP/Fetch nodes – with the intermediate results not updating, the entire purpose of ROP chaining was defeated.)

2012-12-06

  • Santa brought a ((Create Wedge ROP)) button. :)

2012-12-01

Various workflow enhancements (mostly Wedge-related):

  • More convenient default parameter settings on created Wedge ROPs

  • Wedge range can now be explicitly specified

  • Multiple Wedge nodes can now be created (where each is set to “Single Wedge” mode)

  • Target ROP network is created if it doesn’t exist

  • UI: minor layout changes; some pop-up messages turned into status-line feedbacks

2012-11-30

  • Added support for File Merge SOP creation (for loading wedged-seeded geometry).

  • Created File/FileMerge SOPs are now placed right under the Waypoint node in the network.

2012-11-09

  • Minor UI changes (more accessible render/reload buttons, label changes, etc.)

2012-10-02

  • Bug fix: Points Only for Consecutive Frames now uses the first frame of the render range (instead of frame #1).

2012-08-05

  • Full output file (sequence) path is now constructed from three components (path, name, extension) – all represented with a separate parameter. This results in shorter filename expressions.

  • Got rid of multiple inputs, added variants instead (so there’s still built-in support for writing multiple variants of the same input). Variants can be numeric or textual.

  • The output directory is created before writing (if it doesn’t exist).

interface version 1 —

Version 0.0.3

  • Output filename helper “preset” menu

  • Node state (disabled/enabled) feedback both as node color and in a parameter editor message

  • Start/end time for the last few render processes are stored (logged) in the node comment field

  • Performance monitoring

Version 0.0.2

  • Option for clamping the time range to the range set up in the Writer tab

  • Option for writing point data only for all but the first frame

Version 0.0.1

First release.