Skip to content

Developing Operators (Beta) ​

This page is for R&D engineers. It explains how to write operators that can be uploaded to the NexCore operator library and run in pipeline processing.

Permissions

Only R&D engineers can upload operators and configure their parameters. Operator libraries are isolated by project and are not shared across projects.

Package Layout ​

Operators are uploaded as a .zip package:

text
slam_orbslam3_v1.2.0.zip
├── operator.yaml        # Operator descriptor (required)
├── main.py              # Entry script (required; path declared in operator.yaml)
├── requirements.txt     # Python dependencies (optional)
├── assets/              # Static resources such as model weights or vocabularies (optional)
└── README.md            # Documentation (recommended)

A package can be up to 2 GB. For larger files, keep them in object storage and download them at runtime as needed.

Descriptor: operator.yaml ​

yaml
name: slam_orbslam3              # Unique within the project; lowercase letters, digits, and underscores only
version: 1.2.0                   # Semantic version
type: slam                       # slam | vision | depth | tactile
description: Stereo visual SLAM that outputs the camera trajectory
entry: main.py
runtime:
  python: "3.10"
  gpu: true                      # Whether a GPU is required
  timeout_minutes: 60            # Timeout per item
inputs:
  - name: left_video
    type: video
  - name: right_video
    type: video
  - name: calib
    type: yaml
outputs:
  - name: trajectory
    type: table                  # Written to the output directory
    file: trajectory.csv
params:
  - name: feature_count
    type: int
    default: 1500
    min: 500
    max: 5000
  - name: use_imu
    type: bool
    default: false
depends_on: []                   # Names of upstream operators, used to build the pipeline chain
FieldDescription
typeDetermines which output operator type the operator appears under
paramsDeclared parameters appear in the parameter form in the pipeline dialog; read-only for roles other than R&D engineer
depends_onDeclares upstream dependencies, which the platform uses to build the prerequisites → execution → post-processing chain

Runtime Contract ​

The platform launches one operator process per item and passes paths and parameters through environment variables:

VariableDescription
NEXCORE_INPUT_DIRInput directory, mounted read-only
NEXCORE_OUTPUT_DIROutput directory where the operator writes its results
NEXCORE_PARAMSParameter values as a JSON string
NEXCORE_DATA_IDID of the current item
NEXCORE_RUN_IDID of the current pipeline job

Example entry script:

python
import json
import os
from pathlib import Path


def main() -> int:
    input_dir = Path(os.environ["NEXCORE_INPUT_DIR"])
    output_dir = Path(os.environ["NEXCORE_OUTPUT_DIR"])
    params = json.loads(os.environ.get("NEXCORE_PARAMS", "{}"))

    left = input_dir / "video" / "left.mp4"
    right = input_dir / "video" / "right.mp4"
    if not left.exists() or not right.exists():
        print("missing stereo video", flush=True)
        return 2

    # ... run the algorithm and generate the trajectory ...
    (output_dir / "trajectory.csv").write_text("timestamp,x,y,z,qx,qy,qz,qw\n")
    print(f"done, feature_count={params.get('feature_count')}", flush=True)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Exit Codes ​

Exit codeMeaningPlatform behavior
0SuccessCollects the outputs and moves on to the next step
1General errorMarks the step as failed; it can be retried
2Invalid inputMarks the step as failed. Retrying without checking the input data is not recommended.
TimeoutExceeded timeout_minutesTerminates the process and marks the step as failed

Standard output and standard error are captured in the pipeline logs.

Required Rules ​

  • Never modify the input directory. Inputs are mounted read-only; source data must never be rewritten.
  • Never silently delete data. Operators may only produce results, candidate labels, or processing steps; they must not delete or overwrite source data.
  • Write outputs to the output directory. Files written anywhere else are not collected.
  • Be idempotent. Running the same input again should produce the same outputs, so retries are safe.

Testing Locally ​

Before uploading, simulate a run locally:

bash
export NEXCORE_INPUT_DIR=./samples/session_001
export NEXCORE_OUTPUT_DIR=./out
export NEXCORE_PARAMS='{"feature_count": 1500, "use_imu": false}'
export NEXCORE_DATA_ID=local-test
export NEXCORE_RUN_ID=local-run
mkdir -p "$NEXCORE_OUTPUT_DIR"
python main.py; echo "exit code: $?"

Uploading and Versioning ​

  • After upload, the platform validates operator.yaml and the entry file. Only operators that pass are added to the library.
  • If an operator with the same name exists, you are asked to overwrite it or rename the new one. Overwriting doesn't affect completed run history.
  • Bump version with every change so runs are easy to tell apart in the logs.

NexCore is evolving rapidly; the latest version prevails.NexCore Docs · Embodied AI Skill Learning Platform by Lumos Robotics