Path Dictionary

The ovstage.PathDictionary maps strings and prim paths to reusable identifiers. Registering a string this way is called interning. Use the stage’s dictionary so the identifiers your application creates match those used by ovstage.

Create PathDictionary(stage) to borrow the instance-owned dictionary. In C, obtain it with ovstage_get_path_dictionary().

Names, Paths, and Lists

Python method	Result
intern_token(name)	An integer token for a string, such as an attribute name.
intern_path(path)	An integer identifier for a prim path.
create_path_list_from_strings(paths)	An immutable, ordered ovstage.PathList for a query.

Within one dictionary, interning the same string or prim path returns the same identifier. Compare those identifiers directly rather than resolving their strings. Path lists are different: creating the same ordered list twice can return different handles. Do not compare path-list handles to determine whether their contents match. The C types are ovx_token_t, ovx_primpath_t, and ovx_primpath_list_t respectively; their OVX_INVALID_* values are 0 and are not successful results.

Interning and Resolving

Intern a string to a token, then resolve the token back to its string:

Python

# Intern a string -> a stable integer token, and resolve it back.
attr = paths.intern_token("temperature")
print("attribute token", attr, "=", paths.token_to_string(attr))

C

// The path dictionary is owned by the instance (no app-side create/destroy):
// obtain it, intern strings -> stable tokens, and resolve tokens back.
path_dictionary_instance_t* dict = ovstage_get_path_dictionary(stage);
if (!dict)
{
    std::fprintf(stderr, "no path dictionary for instance\n");
    return EXIT_FAILURE;
}

ovx_string_t attrName = literal_to_ovx_string("temperature");
ovx_token_t attr = OVX_INVALID_TOKEN;
ovx_api_result_t ovxResult = path_dictionary_create_tokens_from_strings(dict, &attrName, 1, &attr);
checkOvx(dict, ovxResult, "intern-token");

ovx_string_t resolved{};
ovxResult = path_dictionary_get_strings_from_tokens(dict, &attr, 1, &resolved);
checkOvx(dict, ovxResult, "resolve-token");

Constructing Prim Paths

In Python, use intern_path() with an absolute path such as /World/Box. Use / for the root.

In C, path_dictionary_create_paths_from_tokens() also accepts component names: tokens for World and Box produce /World/Box. Do not include separators in the names. Within one dictionary, this returns the same handle as path_dictionary_create_paths_from_strings(), regardless of call order. Python exposes only string-based path construction.

For the root in C, set its num_tokens_per_path entry to zero. Supply a non-null tokens_per_path array; no component tokens are read for that entry. path_dictionary_get_tokens_from_paths() returns zero components for /.

Building a Path List and Opening a Query

An interned prim-path list is the input to Queries. Build one from strings and open a query over those prims:

Python

# Build an interned prim-path list and open a query over those prims.
# The query is a context manager: block exit releases its handle, and
# Stage teardown requires all handles released first -- the try/finally
# releases the path list even when an error interrupts the flow.
prim_paths = paths.create_path_list_from_strings(["/World/A", "/World/B", "/World/C"])
try:
    with stage.query_from_path_list(prim_paths) as query:

C

// Build an immutable prim-path list from strings and open a query over it.
const ovx_string_t paths[] = { literal_to_ovx_string("/World/A"), literal_to_ovx_string("/World/B"),
                               literal_to_ovx_string("/World/C") };
ovx_primpath_list_t pathList = OVX_INVALID_PRIMPATH_LIST;
ovxResult = path_dictionary_create_path_list_from_strings(dict, paths, 3, &pathList);
checkOvx(dict, ovxResult, "create-path-list");

ovstage_query_handle_t query = OVSTAGE_INVALID_QUERY_HANDLE;
status = ovstage_query_from_path_list(stage, pathList, &query);
check(stage, status, "query_from_path_list");

Attribute Arguments: String or Token

Attribute arguments accept a string or an integer token. Reusing an interned token avoids a string lookup on each call. In C, ovx_string_or_token_t holds either form. These snippets show both:

Python

# Attribute arguments accept an interned token (int) or a plain str:
# a token skips the per-call dictionary lookup, a str is interned for
# you at call time.
stage.write_attribute(
    query, "temperature", ordinal=2, tensors=np.array([4.0, 5.0, 6.0], np.float32),
    is_array=False,
).wait()
stage.advance_write_floor(ordinal=2).wait()

C

// Attributes pass as ovx_string_or_token_t. We already hold an interned
// token, so set it (token != 0) and leave the string empty to skip a lookup.
ovx_string_or_token_t attrArg{ attr, {} };

Ownership and Lifetime

• Each stage owns its dictionary. Python requires PathDictionary(stage); the wrapper does not own the stage. Do not destroy the native dictionary separately.

• Path lists belong to that stage. To use the same selection on another stage, recreate the list in its dictionary. Release list references before destroying their stage; neither a list reference nor another live stage keeps them valid.

• Tokens and individual path identifiers last for the dictionary’s lifetime; do not release them individually.

• create_path_list() and create_path_list_from_strings() return an owned ovstage.PathList. Use a with block or call release(). The object is also an int and can be passed wherever a list handle is accepted. Reuse a list outside a per-frame loop when its paths do not change.

• Lists borrowed from read results remain plain integers. Do not release them.

• An unreleased Python PathList releases its reference on garbage collection and emits ResourceWarning. Explicit release avoids relying on that cleanup.

In C, release each created path-list reference through the dictionary exactly once. Returned ovx_string_t values borrow dictionary storage; copy any text that must outlive the dictionary. See String Handling.

Errors

Python dictionary failures raise ovstage.OvxError. Invalid, unknown, or expired path identifiers fail rather than resolving to an empty string. ovstage.PathDictionary.path_to_string() returns / for the valid absolute root.

In C, dictionary calls return ovx_api_result_t. On OVX_API_ERROR, release the error string with path_dictionary_release_error(). path_dictionary_get_tokens_from_paths() returns component tokens, not a joined path string. The root succeeds as one processed path with zero tokens; callers join the components themselves. See Error Handling and Diagnostics.

Further Reading

• Queries — resolve a path list into per-attribute prim groups.

• Writing Attributes / Reading Attributes — use tokens as attribute keys.

• String Handling — working with ovx_string_t in C.