Node Categories

An OmniGraph node can have one or more categories associated with it, giving the UI a method of presenting large lists of nodes or node types in a more organized manner.

Category Specification In .ogn File

For now the node categories are all specified through the .ogn file, so the node will inherit all of the categories that were associated with its node type. There are three ways you can specify a node type category in a .ogn file; using a predefined category, creating a new category definition inline, or referencing an external file that has shared category definitions.

Predefined Categories

This is the simplest, and recommended, method of specifying categories. There is a single .ogn keyword to add to the file to associate categories with the node type. It can take three different forms. The first is a simple string with a single category in it:

{
    "MyNodeWithOneCategory": {
        "version": 1,
        "categories": "function",
        "description": "Empty node with one category"
    }
}

Warning

The list of categories is intentionally fixed. Using a category name that is not known to the system will result in a parsing failure and the node will not be generated. See below for methods of expanding the list of available categories.

The second is a comma-separated list within that string, which specifies more than one category.

{
    "MyNodeWithTwoCategories": {
        "version": 1,
        "categories": "function,time",
        "description": "Empty node with two categories"
    }
}

The last also specifies more than one category; this time in a list format:

{
    "MyNodeWithAListOfTwoCategories": {
        "version": 1,
        "categories": ["function", "time"],
        "description": "Empty node with a list of two categories"
    }
}

The predefined list is contained within a configuration file. Later you will see how to add your own category definitions. The predefined configuration file looks like this:

{
    "categoryDefinitions": {
        "$description": [
            "This file contains the category information that will tell OGN what the acceptable values for",
            "categories are in the .ogn file under the 'categories' keyword along with descriptions of each of",
            "the categories. Categories have an optional namespace to indicate subcategories, e.g. 'math:vector'",
            "indicates math nodes dealing exclusively with vectors.",
            "",
            "The contents of this file will always denote legal categories. The list can be extended by creating",
            "another file with the same format and adding it under the 'categoryDefinitions' keyword in .ogn, or by",
            "inserting an individual category definition in the 'category' keyword in .ogn. See the docs for details."
        ],
        "bundle": "Nodes dealing with Bundles",
        "constants": "Nodes which provide a constant value",
        "debug": "Development assist nodes for debugging",
        "event": "Action Graph nodes which are event sources for the graph",
        "examples": "Nodes which are used in documentation examples",
        "fileIO": "Nodes relating to data stored in the file system",
        "flowControl": "Nodes dealing with evaluation order of the graph",
        "function": "Nodes implementing a general function",
        "geometry:analysis": "Nodes dealing with the analysis of geometry representations",
        "geometry:deformer": "Nodes that deform geometry in space",
        "geometry:generator": "Nodes that generate different kinds of geometry",
        "geometry": "Nodes dealing with the manipulation of geometry",
        "graph:action": "Nodes specifically relating to action graphs",
        "graph:onDemand": "Nodes specifically relating to on-demand graphs",
        "graph:postRender": "Nodes specifically relating to post-render graphs",
        "graph:preRender": "Nodes specifically relating to pre-render graphs",
        "graph:simulation": "Nodes specifically relating to action graphs",
        "graph": "Nodes dealing with the graph to which they belong",
        "input:gamepad": "Nodes dealing with gamepad input",
        "input:keyboard": "Nodes dealing with keyboard input",
        "input:mouse": "Nodes dealing with mouse input",
        "input": "Nodes dealing with external input sources",
        "internal:test": "Nodes used solely for internal testing",
        "internal:tutorial": "Nodes used solely for illustrating a node writing technique",
        "internal": "Nodes not meant for general use",
        "material:shader": "Nodes dealing with shader information",
        "material:texture": "Nodes dealing with texture information",
        "material": "Nodes dealing with general materials",
        "math:array": "Nodes dealing with operations on arrays",
        "math:casts": "Nodes casting values from one type to another compatible type",
        "math:condition": "Nodes implementing mathematical logic functions",
        "math:constant": "Nodes with a constant value",
        "math:conversion": "Nodes converting between different types of data",
        "math:matrix": "Nodes dealing with matrix math",
        "math:operator": "Nodes implementing a mathematical operator",
        "math:vector": "Nodes dealing with vector math",
        "math": "General math values and functions",
        "rendering": "Nodes dealing with rendering components",
        "sceneGraph:camera": "Nodes dealing with the scene graph directly",
        "sceneGraph": "Nodes dealing with the scene graph directly",
        "script": "Nodes dealing with custom scripts",
        "sound": "Nodes dealing with sound",
        "time": "Nodes dealing with time values",
        "tutorials": "Nodes which are used in a documentation tutorial",
        "ui": "Nodes that create UI widgets and UI containers",
        "variables": "Nodes dealing with variables on the graph",
        "variants": "Nodes dealing with USD variants",
        "viewport": "Nodes dealing with viewport"
    }
}

Note

You might have noticed some categories contain a colon as a separator. This is a convention that allows splitting of a single category into subcategories. Some UI may choose to use this information to provide more fine-grained filtering an organizing features.

Inline Category Definition

On occasion you may find that your node does not fit into any of the predefined categories, or you may wish to add extra categories that are specific to your project. One way to do this is to define a new category directly within the .ogn file.

The way you define a new category is to use a name:description category dictionary rather than a simple string. For example, you could replace a single string directly:

{
    "MyNodeWithOneCustomCategory": {
        "version": 1,
        "categories": {"light": "Nodes implementing lights for rendering"},
        "description": "Empty node with one custom category"
    }
}

You can add more than one category by adding more dictionary entries:

{
    "MyNodeWithTwoCustomCategories": {
        "version": 1,
        "categories": {
            "light": "Nodes implementing lights for rendering",
            "night": "Nodes implementing all aspects of nighttime"
        },
        "description": "Empty node with two custom categories"
    }
}

You can also mix custom categories with predefined categories using the list form:

{
    "MyNodeWithMixedCategories": {
        "version": 1,
        "categories": ["rendering",
            {
                "light": "Nodes implementing lights for rendering",
                "night": "Nodes implementing all aspects of nighttime"
            }
        ],
        "description": "Empty node with mixed categories"
    }
}

Shared Category Definition File

While adding a category definition directly within a file is convenient, it is not all that useful as you either only have one node type per category, or you have to duplicate the category definitions in every .ogn file. A better approach is to put all of your extension’s, or project’s, categories into a single configuration file and add it to the build.

The configuration file is a .json file containing a single dictionary entry with the keyword categoryDefinitions. The entries are name:description pairs, where name is the name of the category that can be used in the .ogn file and description is a short description of the function of node types within that category.

Here is the file that would implement the above two custom categories:

{
    "categoryDefinitions": {
        "$description": "These categories are applied to nodes in MyProject",
        "light": "Nodes implementing lights for rendering",
        "night": "Nodes implementing all aspects of nighttime"
    }
}

Tip

As with regular .ogn file any keyword beginning with a “$” will be ignored and can be used for documentation.

If your extension is building within Kit then you can install your configuration into the build by adding this line to your premake5.lua file:

install_ogn_configuration_file("MyProjectCategories.json")

This allows you to reference the new category list directly from your .ogn file, expanding the list of available categories using the .ogn keyword categoryDefinitions:

{
    "MyNodeWithOneCustomCategory": {
        "version": 1,
        "categoryDefinitions": "MyProjectCategories.json",
        "categories": "light",
        "description": "Empty node with one custom category"
    }
}

Here, the predefined category list has been expanded to include those defined in your custom category configuration file, allowing use of the new category name without an explicit definition.

If your extension is independent, either using the Kit SDK to build or not having a build component at all, you can instead reference either the absolute path of your configuration file, or the path relative to the directory in which your .ogn resides. As with categories, the definition references can be a single value or a list of values:

{
    "MyNodeWithOneCustomCategory": {
        "version": 1,
        "categoryDefinitions": ["myConfigDirectory/MyProjectCategories.json", "C:/Shared/Categories.json"],
        "categories": "light",
        "description": "Empty node with one custom category"
    }
}

Category Access

Access to the existing categories in C++ is done through the omni::graph::core::INodeCategories_abi class. In Python you use the bind to that interface in omni.graph.core.INodeCategories_abi.