New Operation

New Operation

Scaffold a complete Usd Optimize operation plugin from scratch. The output is a buildable, testable plugin with all the wiring in place.

What this skill covers

• Inputs — what the user must provide.
• Step 1 — create the C++ source file.
• Step 2 — create the premake file.
• Step 3 — create the Python test file.
• Step 4 — create the operation guide.
• Step 5 — regenerate the docs (auto-generated; no index to edit).
• Step 6 — (optional) create a validator wrapper.
• Step 7 — build and verify.
• Naming conventions — key, class name, file names.

Companion docs: PLUGINS.md (full plugin authoring reference), docs/cli.rst (how the operation is run once built), .agents/skills/new-validator/SKILL.md (validator authoring recipe).

Inputs

Gather these from the user before scaffolding:

If the user only provides a goal (e.g. "I want to detect X"), help them derive the key, display name, and description before proceeding.

Naming conventions

File-basename convention is a soft rule. Premake auto-discovers any *.cpp under source/operations/<key>/, so the filename isn't enforced. A handful of existing operations diverge (e.g. fitPrimitives/Primitive.cpp for PrimitiveFitOperation, subdivideMeshes/Subdivide.cpp for SubdivideOperation). Prefer the convention for new operations; don't rename existing ones just to match.

Step 1 — Create the C++ source

Create source/operations/<key>/<FileBase>.cpp. Use source/operations/<key>/ as the directory — premake auto-discovers it.

// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0

#include <usd_optimize/core/Core.h>
#include <usd_optimize/core/Operation.h>

namespace usd_optimize
{

constexpr const char* s_category = "<CATEGORY>";

class <ClassName> : public Operation
{
public:
    <ClassName>()
        : Operation("<key>", "<Display Name>", "<Description>")
    {
        // Declare arguments here via addArgument().
        // Example:
        // addArgument("threshold", "Threshold", kDisplayTypeFloat,
        //             "Distance threshold in stage units", m_threshold);
    }

    std::string getDocumentation() const override
    {
        return R"DOC(
Full documentation of what the operation does and when to use it.
)DOC";
    }

    std::string getAuthor() const override
    {
        return "<Author>";
    }

    UsdOptimizePluginVersion getVersion() const override
    {
        return { 1, 0, 0 };
    }

    std::string getCategory() const override
    {
        return s_category;
    }

    std::string getDisplayGroup() const override
    {
        return <display_group_constant>;
    }

    // Uncomment if the operation supports analysis mode:
    // bool getSupportsAnalysis() const override { return true; }

protected:
    OperationResult executeImpl() override
    {
        // TODO: implement
        // OperationResult is a struct (usd_optimize/core/Defs.h), not an enum:
        // { true } is success, { false, getCStr(error) } reports a failure.
        return { true };
    }

    // Uncomment if the operation supports analysis mode:
    // OperationResult executeAnalysisImpl() override
    // {
    //     // TODO: implement analysis (read-only inspection)
    //     return { true };
    // }

private:
    // Member variables bound to arguments:
    // float m_threshold = 0.001f;
};

} // namespace usd_optimize

// Register plugin after the class declaration so this single-file template compiles.
USD_OPTIMIZE_PLUGIN_INIT(usd_optimize::<ClassName>);

Map <display_group_constant> from the user's display group choice:

getCategory() is not the display group. getCategory() returns an UPPER_SNAKE_CASE report-bucket identifier used for grouping log/report output (e.g. existing operations return "COINCIDING", "FIT_PRIMITIVES", "SHRINKWRAP", "OUTPUT"). getDisplayGroup() is a separate concern — it returns one of the four s_displayGroup* constants above and controls UI grouping. Pick a value for each independently; don't substitute one for the other.

If the user provided arguments, add addArgument() calls in the constructor and corresponding member variables. See PLUGINS.md for display types, enum arguments, grouping, and further configuration.

If supportsAnalysis is true, uncomment the analysis stubs.

Step 2 — Create the premake file

Create source/operations/<key>/premake5.lua:

project_with_location("<key>")
    usd_optimize_build.operation_plugin({ "*.cpp" })

This is the standard one-liner. The parent source/operations/premake5.lua auto-discovers it via os.matchfiles("**premake5.lua").

If the operation needs additional libraries beyond the core SDK, add links or includedirs calls after operation_plugin. Look at existing operations (e.g. decimateMeshes, shrinkwrap) for examples of linking third-party deps.

Step 3 — Create the Python test file

Create source/tests/test.python/test_operation_<snake_case>.py:

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

from pxr import Usd, UsdGeom

from .test_utils import Test_Operation


class Test_Operation_<PascalCase>(Test_Operation):

    OPERATION = "<key>"

    async def test_basic(self):
        """Verify the operation runs without error on a trivial stage."""
        stage = Usd.Stage.CreateInMemory()
        UsdGeom.Xform.Define(stage, "/World")
        UsdGeom.Mesh.Define(stage, "/World/Mesh")

        # Set up minimal mesh data so the operation has something to work with
        mesh = UsdGeom.Mesh(stage.GetPrimAtPath("/World/Mesh"))
        mesh.CreatePointsAttr([(0, 0, 0), (1, 0, 0), (1, 1, 0), (0, 1, 0)])
        mesh.CreateFaceVertexCountsAttr([4])
        mesh.CreateFaceVertexIndicesAttr([0, 1, 2, 3])

        _, (success, error, _) = self._execute_command({})
        self.assertTrue(success, f"Operation failed: {error}")

The test uses Test_Operation as the base class, which handles stage caching and teardown. Tests are async by convention (the metaclass wraps them for sync execution). Use self._execute_command(args_dict) to run the operation.

For operations that need fixture files, place them in source/tests/data and load with self._open_stage("fixture.usda").

Step 4 — Document the operation

Operation docs are generated from the C++, so there is no separate Markdown guide to maintain. The per-argument table in docs/operations/<key>.rst is produced automatically from your addArgument() declarations (name, type, default, description) — so write clear description strings there.

For the long-form overview and tuning guidance, override getDocumentation() to return reStructuredText. docs_prebuild.py inserts it between the title and the auto-generated "Arguments" section:

std::string <ClassName>::getDocumentation() const
{
    return R"DOC(One-paragraph overview of what the operation does and when to use it.

Tuning
------

How the key parameters interact, scale/units notes (state metersPerUnit
conversions factually), important non-obvious defaults, and recommended pipelines.

Starting configurations
-----------------------

.. code-block:: json

    [{"operation": "<key>", "<arg>": <val>}]
)DOC";
}

Use - underlines for section headers (same level as the auto-generated "Arguments" section). See an existing operation like decimateMeshes or meshCleanup for the established style. If the logic isn't implemented yet, return a short description and fill in tuning guidance later.

Step 5 — Regenerate the docs

The operation list (docs/operations.rst toctree + summary table) and each per-operation docs/operations/<key>.rst are all auto-generated — there is no index to hand-edit. Regenerate them after building:

./repo.sh docs_gen --autogen_only

Confirm docs/operations/<key>.rst now exists and contains your getDocumentation() text plus the argument table.

Step 6 — (Optional) Create a validator wrapper

If the operation supports analysis mode and a validator is requested, follow the full recipe in .agents/skills/new-validator/SKILL.md.

Step 7 — Build and verify

./repo.sh build
./repo.sh test -s cpp
./repo.sh test -s python

The python suite covers any test_operation_<snake_case>.py and test_validators_<snake_case>.py files you added. The repo's Python test wrapper currently runs the full suite; it does not forward per-file filters to source/tests/test.python/run_discover.py.

Verify the operation is registered:

# Should print True
python3 -c "from usd_optimize.core import UsdOptimizeCore; print('<key>' in UsdOptimizeCore.getInstance().getOperations())"

See also

• PLUGINS.md — full plugin authoring guide (arguments, display types, enums, groups, analysis mode, registration).
• docs/operations/ — the generated per-operation references (your getDocumentation() output lands here).
• docs/cli.rst — how operations are run via the usdOptimize CLI.
• .agents/skills/run-validators/SKILL.md — validator infrastructure, programmatic API, CLI gotchas.
• .agents/skills/new-validator/SKILL.md — validator authoring recipe.

Purpose

Stand up a complete, buildable, testable operation plugin from scratch — the C++ source, premake build entry, Python binding test, getDocumentation() docs, and an optional validator wrapper. The output compiles, registers, and runs after ./repo.sh build even before any operation logic is implemented (the stub executeImpl returns success).

Prerequisites

• A built repo (./repo.sh build or repo.bat build) so the scaffolded plugin links and its tests can run.
• The user's intent in concrete form: operation key, display name, description, display group, and optionally arguments + analysis-mode flag. The skill prompts for any missing inputs before generating files.
• Write access to the source tree: source/operations/, source/tests/test.python/, and docs/operations/ (regenerated).

Limitations

• The scaffold compiles but does not implement the operation logic — executeImpl() returns { true } as a stub. The author wires up the actual algorithm in a follow-up pass.
• The generated guide leaves Overview / Tuning Order / Visual Diagnosis sections marked with HTML-comment TODO markers (literal text TODO(developer) wrapped in an HTML comment) until the author fills them in or runs the tune-parameters Guide Authoring Mode.
• The validator step is optional and only meaningful when the operation supports analysis mode.
• Cross-platform compilation (Windows + Linux) and any third-party dependency wiring beyond the SDK is the author's responsibility.

Troubleshooting