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| Field | Description |
|---|---|
type | Determines which output operator type the operator appears under |
params | Declared parameters appear in the parameter form in the pipeline dialog; read-only for roles other than R&D engineer |
depends_on | Declares 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:
| Variable | Description |
|---|---|
NEXCORE_INPUT_DIR | Input directory, mounted read-only |
NEXCORE_OUTPUT_DIR | Output directory where the operator writes its results |
NEXCORE_PARAMS | Parameter values as a JSON string |
NEXCORE_DATA_ID | ID of the current item |
NEXCORE_RUN_ID | ID 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 code | Meaning | Platform behavior |
|---|---|---|
0 | Success | Collects the outputs and moves on to the next step |
1 | General error | Marks the step as failed; it can be retried |
2 | Invalid input | Marks the step as failed. Retrying without checking the input data is not recommended. |
| Timeout | Exceeded timeout_minutes | Terminates 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.yamland 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
versionwith every change so runs are easy to tell apart in the logs.

