Extension: omni.graph.template.python-1.20.0

Documentation Generated: Oct 24, 2024

Changelog

Overview

This is the gold standard template for creating a Kit extension that contains only Python OmniGraph nodes.

The Files

To use this template first copy the entire directory into a location that is visible to your build, such as source/extensions. The copy will have this directory structure. The highlighted lines should be renamed to match your extension, or removed if you do not want to use them.

omni.graph.template.python/
    config/
        extension.toml
    data/
        icon.svg
        preview.png
    docs/
        CHANGELOG.md
        directory.txt
        Overview.md
        README.md
    premake5.lua
    python/
        __init__.py
        _impl/
            __init__.py
            extension.py
        nodes/
            OgnTemplateNodePy.ogn
            OgnTemplateNodePy.py
        tests/
            __init__.py
            test_api.py
            test_omni_graph_template_python.py

The convention of having implementation details of a module in the _impl/ subdirectory is to make it clear to the user that they should not be directly accessing anything in that directory, only what is exposed in the __init__.py.

The Build File

Kit normally uses premake for building so this example shows how to use the template premake5.lua file to customize your build. By default the build file is set up to correspond to the directory structure shown above. By using this standard layout the utility functions can do most of the work for you.

 1-- --------------------------------------------------------------------------------------------------------------------
 2-- Build file for the build tools used by the OmniGraph Python template extension. These are tools required in order to
 3-- run the build on that extension, and all extensions dependent on it.
 4
 5-- --------------------------------------------------------------------------------------------------------------------
 6-- This sets up a shared extension configuration, used by most Kit extensions.
 7local ext = get_current_extension_info()
 8
 9-- --------------------------------------------------------------------------------------------------------------------
10-- Set up a variable containing standard configuration information for projects containing OGN files.
11-- The string corresponds to the Python module name, in this case omni.graph.template.python.
12local ogn = get_ogn_project_information(ext, "omni/graph/template/python")
13
14-- --------------------------------------------------------------------------------------------------------------------
15-- Put this project into the "omnigraph" IDE group. You might choose a different name for convenience.
16ext.group = "omnigraph"
17
18-- --------------------------------------------------------------------------------------------------------------------
19-- Define a build project to process the ogn files to create the generated code that will be used by the node
20-- implementations. The (optional) "toc" value points to the directory where the table of contents with the OmniGraph
21-- nodes in this extension will be generated. Omit it if you will be generating your own table of contents.
22project_ext_ogn( ext, ogn, { toc="docs/Overview.md" } )
23
24-- --------------------------------------------------------------------------------------------------------------------
25-- Build project responsible for generating the Python nodes and installing them and any scripts into the build tree.
26project_ext( ext, { generate_ext_project=true })
27
28    -- These lines add the files in the project to the IDE where the first argument is the group and the second
29    -- is the set of files in the source tree that are populated into that group.
30    add_files("python", "*.py")
31    add_files("python/_impl", "python/_impl/**.py")
32    add_files("python/nodes", "python/nodes")
33    add_files("python/tests", "python/tests")
34    add_files("docs", "docs")
35    add_files("data", "data")
36
37    -- Add the standard dependencies all OGN projects have. The second parameter is a table of all directories
38    -- containing Python nodes. Here there is only one.
39    add_ogn_dependencies(ogn, {"python/nodes"})
40
41    -- Copy the init script directly into the build tree. This is required because the build will create an ogn/
42    -- subdirectory in the Python module so only the subdirectories can be linked.
43    repo_build.prebuild_copy {
44        { "python/__init__.py", ogn.python_target_path },
45    }
46
47    -- Linking directories allows them to hot reload when files are modified in the source tree.
48	-- Docs are linked to get the README into the extension window.
49    -- Data contains the images used by the extension configuration preview.
50    -- The "nodes/" directory does not have to be mentioned here as it will be handled by add_ogn_dependencies() above.
51    repo_build.prebuild_link {
52        { "docs", ext.target_dir.."/docs" },
53        { "data", ext.target_dir.."/data" },
54        { "python/tests", ogn.python_tests_target_path },
55        { "python/_impl", ogn.python_target_path.."/_impl" },
56    }
57
58-- With the above copy/link operations this is what the source and build trees will look like
59--
60-- SOURCE                             BUILD
61-- omni.graph.template.python/        omni.graph.template.python/
62--   config/                            config@ -> SOURCE/config
63--   data/                              data@ -> SOURCE/data
64--   docs/                              docs@ -> SOURCE/docs
65--   python/                            ogn/  (generated by the build)
66--     __init__.py                      omni/
67--     _impl/                             graph/
68--     nodes/                               template/
69--                                            python/
70--                                              __init__.py  (copied from SOURCE/python)
71--                                              _impl@ -> SOURCE/python/_impl
72--                                              nodes@ -> SOURCE/python/nodes
73--                                              tests@ -> SOURCE/python/tests
74--                                              ogn/  (Generated by the build)

By convention the installed Python files are structured in a directory tree that matches a namespace corresponding to the extension name, in this case omni/graph/template/python/, which corresponds to the extension name omni.graph.template.python. You’ll want to modify this to match your own extension’s name. Changing the first highlighted line is all you have to do to make that happen.

The Configuration

Every extension requires a config/extension.toml file with metadata describing the extension to the extension management system. Below is the annotated version of this file, where the highlighted lines are the ones you should change to match your own extension.

 1# Main extension description values
 2[package]
 3# The current extension version number - uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 4version = "1.20.0"
 5# The title of the extension that will appear in the extension window
 6title = "OmniGraph Python Template"
 7# Longer description of the extension
 8description = "Templates for setting up an extension containing OmniGraph Python nodes only (no C++)."
 9# Authors/owners of the extension - usually an email by convention
10authors = ["NVIDIA <no-reply@nvidia.com>"]
11# Category under which the extension will be organized
12category = "Graph"
13# Location of the main README file describing the extension for extension developers
14readme = "docs/README.md"
15# Location of the main CHANGELOG file describing the modifications made to the extension during development
16changelog = "docs/CHANGELOG.md"
17# Location of the repository in which the extension's source can be found
18repository = "https://gitlab-master.nvidia.com/omniverse/kit-extensions/kit-omnigraph"
19# Keywords to help identify the extension when searching
20keywords = ["kit", "omnigraph", "nodes", "python"]
21# Image that shows up in the preview pane of the extension window
22preview_image = "data/preview.png"
23# Image that shows up in the navigation pane of the extension window - can be a .png, .jpg, or .svg
24icon = "data/icon.svg"
25# Specifying this ensures that the extension is always published for the matching version of the Kit SDK
26writeTarget.kit = true
27# Specify the minimum level for support
28support_level = "Sample"
29
30# Main module for the Python interface. This is how the module will be imported.
31[[python.module]]
32name = "omni.graph.template.python"
33
34# Watch the .ogn files for hot reloading. Only useful during development as after delivery files cannot be changed.
35[fswatcher.patterns]
36include = ["*.ogn", "*.py"]
37exclude = ["Ogn*Database.py"]
38
39# Other extensions that need to load in order for this one to work
40[dependencies]
41"omni.graph" = {}       # For basic functionality
42"omni.graph.tools" = {} # For node generation
43
44# Main pages published as part of documentation. (Only if you build and publish your documentation.)
45[documentation]
46pages = [
47    "docs/Overview.md",
48    "docs/CHANGELOG.md",
49]
50
51# Some extensions are only needed when writing tests, including those automatically generated from a .ogn file.
52# Having special test-only dependencies lets you avoid introducing a dependency on the test environment when only
53# using the functionality.
54[[test]]
55dependencies = [
56    "omni.kit.test"  # Brings in the Kit testing framework
57]

Contained in this file are references to the icon file in data/icon.svg and the preview image in data/preview.png which control how your extension appears in the extension manager. You will want to customize those.

Documentation

Everything in the docs/ subdirectory is considered documentation for the extension.

  • README.md The contents of this file appear in the extension manager window so you will want to customize it. The location of this file is configured in the extension.toml file as the readme value.

  • CHANGELOG.md It is good practice to keep track of changes to your extension so that users know what is available. The location of this file is configured in the extension.toml file as the changelog value, and as an entry in the [documentation] pages.

  • Overview.md This contains the main documentation page for the extension. It can stand alone or reference an arbitrarily complex set of files, images, and videos that document use of the extension. The toctree reference at the bottom of the file contains at least GeneratedNodeDocumentation/, which creates links to all of the documentation that is automatically generated for your nodes. The location of this file is configured in the extension.toml file in the [documentation] pages section.

  • directory.txt This file can be deleted as it is specific to these instructions.

The Node Type Definitions

You define a new node type using two files, examples of which are in the nodes/ subdirectory. Tailor the definition of your node types for your computations. Start with the OmniGraph User Guide for information on how to configure your own definitions.

Tests

While completely optional it’s always a good idea to add a few tests for your node to ensure that it works as you intend it and continues to work when you make changes to it. Automated tests will be generated for each of your node type definitions to exercise basic functionality. What you want to write here are more complex tests that use your node types in more complex graphs.

The sample tests in the tests/ subdirectory show you how you can integrate with the Kit testing framework to easily run tests on nodes built from your node type definition.

That’s all there is to creating a simple Python node type! You can now open your app, enable the new extension, and your sample node type will be available to use within OmniGraph.

OmniGraph Nodes In This Extension