build-ncore-converter
Skill33 starsChanged 17 days agoApache-2.0View on GitHub
Source execution: Read $NUREC_WORKDIR/nurec-runtime.md, generated by run.sh, before executing commands. For every root-workspace bazel command below, use its literal Docker/Bazel prefix with the same target and arguments. Only the standalone converter workspace runs Bazel on the host. Do not extract release archives into host caches or invent module overrides. This is the operating specification for an autonomous step that scaffolds, implements, and iteratively fixes an NCore V4 data converter. The agent reads this file, receives an input description, and executes…
- Installs packages
In this repository10 other files it gives its agents.
- nurec/libs/losses/AGENTS.mdAGENTS.md
- skills/nurec-onboard/AGENTS.mdAGENTS.md
- skills/nurec-onboard/CLAUDE.mdCLAUDE.md
- nurec-onboardSkill
- audit-datasetSkill
- run-nurecSkill
- validate-ncore-dataSkill
- nurecSkill
- physical-ai-av-benchmarkSkill
- physical-ai-datasetsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
33 rules. About 0 are common, 8 are distinctive, and 25 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
25
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Source execution: Read $NUREC_WORKDIR/nurec-runtime.md, generated by run.sh, before executing commands.
- Distinctive: line 11
Only the standalone converter workspace runs Bazel on the host.
- Distinctive: line 22
When building or fixing a converter the agent MUST draw implementation decisions exclusively from:
- Very specific: line 31
Every implementation decision must be recorded as a critical_parameter_justification with evidence drawn from sources (1)–(4) above.
- Very specific: line 85
If ncore.converter_dir is not provided, derive it: $NUREC_WORKDIR/ncore-<data.name>.
- Very specific: line 88
Treat lib/parse_input.py as the source of truth for input shape and scope validation before the step starts.
- Very specific: line 89
If ncore is present, use its camera_ids and lidar_ids as the conversion output scope.
- Very specific: line 91
If both seek_sec and duration_sec are absent, convert the full available sequence.
- Distinctive: line 92
If exactly one is present, fail fast with a clear input error.
- Very specific: line 93
If both are present, require non-negative numeric values and pass them unchanged to the converter run as --seek-sec <seek_sec> …
- Very specific: line 109
Structured profile precedence: If data.profile is present, read it before data.description.
- Very specific: line 117
Calibration direction evidence: When data.profile records a transform direction convention or known calibration mismatch, use that evidence …
- Very specific: line 157
Operator-scoped sensors: when camera_ids / lidar_ids is provided, every listed id must resolve to a discovered sensor directory (fail fast …
- Distinctive: line 163
Every sensor's calibration: intrinsics, extrinsics, model, rolling-shutter direction.
- Very specific: line 184
Every field of a LiDAR sample -- flag any field whose shape matches a range-image spatial dim ([H, W, ...], [H], or [W]) and whose values …
- Very specific: line 198
Write the summary to <data.name>_meta.json at the workdir root.
- Very specific: line 263
Use data.name as the canonical <dataset> token (the same value that derives ncore.converter_dir).
- Very specific: line 271
Update ncore_<dataset>/BUILD.bazel to reflect the new filenames if any non-converter.py/dataset_probe.py modules were added.
- Very specific: line 272
Add any remaining pip deps to deps/pip/requirements_3_X.in (whichever Python the converter is currently pinned to), regenerate the …
- Very specific: line 291
Before running the converter, sanity-check the output against the conventions.md "NCore convention checklist": frames, timestamps, pose …
- Very specific: line 315
When the input supplies seek_sec / duration_sec, append them as --seek-sec=<seek_sec> --duration-sec=<duration_sec> to the bazel command …
- Very specific: line 326
Add requirement("package-name") to the converter's BUILD.bazel deps.
- Very specific: line 331
Consider whether the failure is fixable by bumping python_version per the Python-bump rule (e.g.
- Very specific: line 342
Check the output directory contains the sequence directory and {sequence_id}.json meta file.
- Distinctive: line 406
Read the relevant converter code section.
- Distinctive: line 408
If multiple fixes are needed, apply them all before re-running.
- Very specific: line 425
FILL IN check: run grep -rn "FILL IN" $ncore_converter_dir/ncore_*/.
- Distinctive: line 426
Must return no matches.
- Very specific: line 428
Justifications validator: if any critical parameter was changed by a fix, re-run cd "$NUREC_ONBOARD_DIR" && bazel run …
- Very specific: line 471
No system pip: never run pip install. All packages go through deps/pip/requirements_3_X.in.
- Very specific: line 474
Never invoke system Python (python3 -c, python3 script.py, or any other system Python call) for code that imports ncore — system Python …
- Distinctive: line 479
No git writes: do not commit or push. Track original files for revert if needed.
- Very specific: line 480
Bazel commands: always cd $ncore_converter_dir first.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->Build NCore V4 Converter
Source execution: Read $NUREC_WORKDIR/nurec-runtime.md, generated by
run.sh, before executing commands. For every root-workspace bazel command
below, use its literal Docker/Bazel prefix with the same target and arguments.
Only the standalone converter workspace runs Bazel on the host. Do not extract
release archives into host caches or invent module overrides.
This is the operating specification for an autonomous step that scaffolds, implements, and iteratively fixes an NCore V4 data converter. The agent reads this file, receives an input description, and executes without user interaction.
Permitted sources
When building or fixing a converter the agent MUST draw implementation decisions exclusively from:
- Converter template — scaffold, helpers, and example code inside the converter workdir (materialized from the bundled template at
$NUREC_ONBOARD_DIR/ncore_template/). - NCore public documentation and SDK —
ncore/docs/,ncore/tools/data_converter/, the NCore Python API. data.docs— the dataset's own documentation (URL, file, or inline text from the input YAML).- Direct data exploration — empirical measurements from
data.pathvia the probe script and Bazel run targets.
The agent MUST NOT consult any pre-existing converter for this dataset (prior runs under the working directory, NCore in-tree converters for other datasets, or any third-party converter on disk).
Every implementation decision must be recorded as a critical_parameter_justification with evidence drawn from sources (1)–(4) above.
1. Input Schema
# Required
data:
name: <string> # Short dataset identifier, filesystem-safe (alphanumeric, dash, underscore)
path: <string> # Path to raw sensor data
description: <string> # Short high-level overview of the dataset.
# Optional
# Dataset documentation: each entry is a file path, URL, or inline text.
# Pass a single string for one source, or a list for multiple (paper +
# devkit + datasheet, etc.). All entries are read and cited individually in
# critical_parameter_justifications evidence.
docs: <string> | [<string>, ...]
# Optional structured dataset facts from audit-dataset. When present, read
# this before description. Evidence-backed facts are authoritative;
# UNRESOLVED high-risk facts are hypotheses to verify.
profile: <mapping>
ncore:
camera_ids: [<string>, ...] # Optional conversion camera scope.
lidar_ids: [<string>, ...] # Optional conversion LiDAR scope.
seek_sec: <number|null> # Optional conversion start offset.
duration_sec: <number|null> # Optional conversion duration.
converter_dir: <string|null> # Default: $NUREC_WORKDIR/ncore-<data.name>
output_dir: <string|null> # Default: <ncore.converter_dir>-out
# Present only in fix mode (passed by nurec-onboard orchestrator)
diagnosis:
source: <string> # "validate-ncore-data" or "run-nurec"
errors: [<string>] # Validation error messages or NuRec symptoms
metrics: { <string>: <value> } # Eval metrics that are out of range
suggested_fixes: [<string>] # Mapped fix suggestions from ../validate-ncore-data/common-failures.mdMode detection
- Scaffold mode:
diagnosisfield is absent. First run -- explore data, scaffold converter, implement, run conversion. - Fix mode:
diagnosisfield is present. Re-invocation -- apply targeted fixes to the converter based on the diagnosis, re-run conversion.
2. Scaffold Mode
Step attempt entry anchor (scaffold mode): capture
runs[*].started_athere, before the "Parse input" actions below; see nurec-onboard/SKILL.md "Timestamp capture rules" for the step-attempt definition.
Parse input and infer sensor properties
- Parse input: extract
data.name,data.path,data.description, optionaldata.profile, optionaldata.docs, optionalncore.converter_dir, optionalncore.output_dir(default:<ncore.converter_dir>-out), and optional conversion scope from top-levelncore.- If
ncore.converter_diris not provided, derive it:$NUREC_WORKDIR/ncore-<data.name>. - If
ncore.converter_dirdoes not yet exist, create it by materializing the bundled template withrsync -a --exclude='tests/' "$NUREC_ONBOARD_DIR/ncore_template/" "<ncore.converter_dir>/". Thetests/exclusion drops the template's platform self-verification regression test (ncore_example_test.py), which is CI-only and not part of the operator's converter; every other file -- including the committedMODULE.bazel.lock-- is copied verbatim. Preserving that lock file is what lets the converter workspace's firstbazelinvocation skip module-extension re-evaluation (and the unreliable pypi.org metadata fetch it would trigger from inside the sandbox). The trailing slash on the source path is required byrsyncto copy the directory's contents into<ncore.converter_dir>/rather than nesting anothertemplate/level inside. - Maintainers who change the bundled template's
MODULE.bazelordeps/pip/requirements_3_13.txtmust refreshncore_template/MODULE.bazel.lockoutside the sandbox withbazel build //... --lockfile_mode=update --nobuildfrom the template root before publishing the template. - Treat
lib/parse_input.pyas the source of truth for input shape and scope validation before the step starts. - If
ncoreis present, use itscamera_idsandlidar_idsas the conversion output scope. These fields control which components are written, not which sensor implementations the converter supports. Cuboids are governed bydata.profile.cuboids; always write aCuboidsComponent, even with zero observations. - Validate the optional conversion time window from
ncore:- If both
seek_secandduration_secare absent, convert the full available sequence. - If exactly one is present, fail fast with a clear input error.
- If both are present, require non-negative numeric values and pass them unchanged to the converter run as
--seek-sec <seek_sec> --duration-sec <duration_sec>.
- If both
- If
- Read documentation (if
data.docsis provided):data.docsaccepts either a single string or a list of strings. Each item is one of: a file path (/or./prefix), a URL (http://orhttps://prefix), or inline text. Read every item and treat them collectively as the dataset's documentation surface; cite the specific item by URL / filename inevidenceso the operator can trace claims back to a source. When an item fails to load (URL fetch fails after one retry, or path missing), record the failure innotesand derive the affected sections empirically.- Mandatory citation coverage. For
camera_timestamp_meaning,lidar_frame_timestamp_meaning, andcuboid_centroid_convention,evidencemust either quote one of thedata.docsitems with a section/page anchor, or -- when all docs are silent or absent -- explicitly say so AND back the chosen value with an inline empirical measurement (cross-sensor offset, ground-clearance histogram, etc.).build_ncore_converter_validator.pyfails on blank or placeholder evidence. - Structured profile precedence. If
data.profileis present, read it beforedata.description. Treat evidence-backed profile entries as the authoritative structured statement of operator/audit-supplied dataset facts. TreatUNRESOLVED:entries, especially high-risk geometric and optical facts from audit-dataset, as hypotheses to verify through the critical-parameter justification step. Treatdata.descriptionas a high-level overview only and do not mine it for detailed facts that conflict with evidence-backeddata.profileentries. - Calibration direction evidence. When
data.profilerecords a transform direction convention or known calibration mismatch, use that evidence before trusting a raw field name. NCore stores poses as source-to-target transforms, so a field label is not sufficient evidence that the matrix is already in the direction required bystore_static_poseorstore_dynamic_pose.
Add dataset-specific dependencies early. Determine which Python package(s) parse this dataset. The converter imports the reader directly so its decoder logic (frame corrections, calibration accessors, point-cloud extraction) runs as-shipped rather than re-implemented. Pick from the ladder below in order; record the choice as
dependency_strategyininferred_parameters. Exploration scripts default tobazel run; system Python is allowed only when the chosen strategy is the preprocess-step fallback, where the reader is not Bazel-resolvable -- see the data-exploration step's probe spec for the matching probe invocation.The four options (direct pip dep → Bazel dep +
sys.pathshim → vendor a slice → preprocess-step fallback), their escalation triggers, and the preprocess script's hard requirement are in dependency-strategies.md. Default to Option 1 and escalate only when the current option actually fails.Explore the raw data directory (
data.path) via a reusable reconnaissance script. The template materialized into the converter dir already includes$ncore_converter_dir/ncore_example/dataset_probe.py-- fill in the dataset-specific logic in place (no rename of this file is required; the scaffold step's single-token rename moves the whole package directory toncore_<dataset>/, after which the probe is atncore_<dataset>/dataset_probe.py). Run it under the toolchain matchingdependency_strategy:bazel run :probe -- --root-dir <path> --output <path>for Bazel-resident strategies,python3 ncore_<dataset>/dataset_probe.py --root-dir <path> --output <path>under the dataset SDK's external env for the preprocess-step fallback. It MUST enumerate:- Every subdirectory under
data.pathwith an explicit decision per directory: include / exclude, modality (camera / lidar / radar / pose / annotation / other), and a one-line reason. Resolve ambiguous directories by inspecting a sample frame -- never silently drop or include. Record undersensor_inventory_decisions. Operator-scoped sensors: whencamera_ids/lidar_idsis provided, every listed id must resolve to a discovered sensor directory (fail fast otherwise); listed ids are included, every other discovered camera / LiDAR is excluded (non-camera / non-LiDAR decisions unchanged). Setdecision_sourcetooperator_include,operator_exclude, oragent_decidedper entry. - Sequence directory layout (list of sequences, one canonical id per sequence).
- Every sensor's calibration: intrinsics, extrinsics, model, rolling-shutter direction.
- Every per-ray metadata stream alongside each LiDAR frame's
(x, y, z). Streams appear as (a) extra fields in the primary payload, (b) companion files in the frame dir, or (c) implicit structured ordering on a densen_rows x n_columnsgrid. Check all three. For each stream record the form, semantic role (ring / column / azimuth / timestamp / intensity / ...), dtype, and length relative to point count. See conventions.md "Per-ray metadata discovery". - One representative frame of every timestamp field (per-frame camera, per-frame LiDAR, per-point LiDAR, pose, cuboid) with unit and min/max/delta across the sequence.
- Sequence frame-range intersection. Compute each required modality's [min, max]
timestamp envelope (every camera, every LiDAR, pose, cuboids); the authoritative
sequence interval is their intersection. Record the bounds, the limiting modality
per side, the excluded-frame count, and the cuboid track counts expected versus
stored under
sequence_frame_range_decision. See conventions.md "Sequence frame-range intersection" for the silent-degradation rationale. - Cross-sensor frame correspondence. Record retained key/index ranges, frame counts, gaps, and duplicates per stream, and establish correspondence by shared source keys or by timestamp -- never by zipping independently filtered arrays. See conventions.md "Sequence frame-range intersection" for the pairing rules and the offset diagnostics.
- Every field of a LiDAR sample -- flag any field whose shape matches a range-image
spatial dim (
[H, W, ...],[H], or[W]) and whose values look like poses or per-ray timestamps. That is per-ray motion metadata and indicates a polar range image. - Metrics that feed
critical_parameter_justifications: per-sensor Z-offset, LiDAR sweep duration, camera exposure/readout durations, per-frame LiDAR↔camera midpoint deltas, cuboid ground-clearance histogram. - One example of every label type (cuboid, 2D box, segmentation mask, ...) with raw field names preserved.
- Image / point-cloud format details (JPEG/PNG, resolution; cartesian vs. polar; units).
- Whether cuboid annotations exist; determine the centroid convention if so. If absent,
_write_cuboidsmust still write an emptyCuboidsComponent(ncore-aux-data asserts the component exists). - The meaning of the LiDAR per-frame timestamp (sweep start / center / end / pose ref).
Write the summary to
<data.name>_meta.jsonat the workdir root.critical_parameter_justificationsmay cite keys in that file instead of restating measurements. Re-running the script after writing the converter is the fastest way to confirm the raw data hasn't changed.- Every subdirectory under
- Record inferred parameters in the output summary based on the exploration:
inferred_parameters:
sensor_suite:
cameras: [{ id, model, resolution: [w, h], rolling_shutter: <bool> }]
lidars: [{ id, type, rows, cols }]
radars: [{ id }]
rig_frame: { x, y, z } # e.g. forward, left, up
timestamp_unit: <string> # Must become microseconds in the converted NCore data.
data_layout: <string>
has_annotations: <bool>
dependency_strategy: pip | bazel_dep_shim | vendored | preprocess # Chosen ladder option from the input-inference step.
python_version_bump: <string|null> # New `MODULE.bazel` python_version if bumped under Option 1; null otherwise.- Justify critical parameters in the output summary -- silent failure modes that
validate.pyandbuild_ncore_converter_validator.pyvalidate. Every entry must populate all four required fields (parameter,value,evidence,wrong_value_consequence). See critical-parameters.md for the entry schema, evidence rules, theworked_examplerequirement onT_lidar_rig/spinning_lidar_model_frame_choice(single-ray prediction),T_camera_rig(per-camera rotation + conditionally-mandatory translation prediction),camera_model_family(per-camera source-derived projection samples), andsequence_frame_range_decision(per-track check count and sampled source cuboid tracks), theauthoritative_sourcesub-block required onT_lidar_rigandT_camera_rig(including itsverificationsub-block), and the value domain plusconventions.mdanchor for each parameter. Required parameter names, by category:- LiDAR model:
spinning_direction,row_elevations_rad,column_azimuths_rad,row_azimuth_offsets_rad,spinning_lidar_model_frame_choice - Sensor enumeration:
sensor_inventory_decisions - NuRec LiDAR selection:
nurec_lidar_selection - Sequence frame range:
sequence_frame_range_decision - LiDAR model provenance:
lidar_model_source - Extrinsics:
T_lidar_rig,camera_frame_convention,T_camera_rig,rig_frame_convention - Cuboids:
cuboid_dim_axis_ordering,cuboid_centroid_convention,cuboid_world_anchored_frame - Timestamps:
timestamp_unit,camera_timestamp_meaning,lidar_frame_timestamp_meaning - Camera shutter:
shutter_type_and_direction— include the rolling-shutter period (T_rs) source. A documented rolling shutter keeps its directional rolling type even when T_rs is unpublished; never guess T_rs. UseShutterType.GLOBALwithstart == endonly when the documentation is silent on shutter type and no source provides T_rs. See conventions.md "Frame timestamps" for the rationale (a wrong T_rs causes multi-camera blur). - LiDAR data:
lidar_raw_format,lidar_motion_compensation,image_distortion_state - Camera intrinsics:
camera_model_family-- include per-camera projection samples derived independently from the source data (for example, LiDAR-to-image correspondences) so the validator can project through the stored NCore camera model and catch pinhole/fisheye/ftheta mismatches. - Camera masks:
camera_static_mask_handling - Pose trajectory:
pose_trajectory_source,lidar_point_frame - LiDAR intensity:
intensity_normalization_method
- LiDAR model:
Scaffold the converter
The materialized template is scaffolding -- rename and adapt it for the target dataset using a single-token substitution: replace example with <dataset> everywhere it appears as a token in the workdir. The placeholder is encoded so that one consistent rename produces a working converter package whose target labels, file names, and class names all line up.
- Use
data.nameas the canonical<dataset>token (the same value that derivesncore.converter_dir); do not infer it fromdata.descriptionor the data directory name. cd $ncore_converter_dir- Apply the single-token rename across the workdir:
- Package directory:
ncore_example/→ncore_<dataset>/. - Class names inside
ncore_<dataset>/converter.py:ExampleConverter→<Dataset>Converter,ExampleConverterConfig→<Dataset>ConverterConfig. Also update the correspondingcli.command("example")decorator andexample_cmdfunction name tocli.command("<dataset>")/<dataset>_cmd. - Import lines anywhere in the workdir: any
from ncore_example.<module> import ...→from ncore_<dataset>.<module> import .... This covers bothconverterandutils(and any future internal modules added under the package). Intra-package imports must stay in the absolutefrom ncore_<dataset>.<module> import ...form --bazel run :convertandbazel run :probeexecute their entry-point module as__main__, wherefrom .<sibling> import ...raisesImportError: attempted relative import with no known parent package. - File names inside the package (
converter.py,dataset_probe.py) and the Bazel target name (convert) are dataset-neutral and stay unchanged. No file renames insidencore_<dataset>/are required after the package rename.
- Package directory:
- Do not rename the Bazel module or pip hub identifiers -- specifically, leave
module(name = "ncore_template"),pip.parse(hub_name = "ncore_template_pip_deps"), anduse_repo(pip, "ncore_template_pip_deps")exactly as shipped. The Bazel module name and pip hub name are internal identifiers that no Python code or BUILD target depends on; touching them at scaffold time invalidatesMODULE.bazel.lock(the warm copy inherited from the bundled template) and forces Bazel to re-evaluate module extensions on the next agent invocation. From inside the sandbox that re-evaluation is unreliable --rules_python's publish-depspip.parsefetches metadata over Bazel's JVM HTTP client, which several network setups don't pass cleanly. Once scaffold has produced a working converter, the operator can rename the module identifiers later (e.g. for namespacing or eventual publishing) by runningbazel mod deps --lockfile_mode=updateoutside the sandbox to refresh the lock, then resuming agent work; that's an operator maintenance task, not a scaffold-step one. OtherMODULE.bazeledits -- addingbazel_dep/http_archiveper Option 2, bumpingpython_versionper the Option 1 escalation, or updating existingbazel_depversions -- are allowed when justified by the dependency-strategy ladder; those edits invalidate the lock at a finer granularity that the same step regenerates. - Update
ncore_<dataset>/BUILD.bazelto reflect the new filenames if any non-converter.py/dataset_probe.pymodules were added; the shippedlib(py_library) andconvert(py_binary) target names stay the same. - Add any remaining pip deps to
deps/pip/requirements_3_X.in(whichever Python the converter is currently pinned to), regenerate the lockfile, and addrequirement()entries in the renamed BUILD.bazel (see the dependency-strategy ladder for the full process and the four sanctioned options).
Fill in the skeleton
The skeleton has FILL IN markers at every dataset-specific value. Every marker must be
resolved -- either replaced with a real value derived from the dataset, or removed when the
surrounding code is rewritten. After this step, grep "FILL IN" <converter>.py must return
no matches (this is verified in Verify output).
Complete each marker using the inferred sensor properties from
Parse input and infer sensor properties.
The scaffolded converter documents every marker inline: each FILL IN comment in
ncore_<dataset>/converter.py states what to implement, the dtype / convention
traps, and the validate.py check it must satisfy. Work through those comments
directly and consult conventions.md for the per-parameter
rationale and deep dives.
NCore convention checklist
Before running the converter, sanity-check the output against the
conventions.md "NCore convention checklist":
frames, timestamps, pose dtypes, pose trajectory, camera frame_timestamps_us,
LiDAR frames, and cuboids. Each item is enforced by the NCore V4 writer or the
shard validator at //skills/nurec-onboard/ncore_validation:validate.
Run the converter
cd $ncore_converter_dir && bazel run //ncore_<dataset>:convert -- \
--root-dir=<data.path> \
--output-dir=<ncore_output_dir> \
[--seek-sec=<seek_sec> --duration-sec=<duration_sec>] \
<subcommand> --store-type itar(Before the scaffold rename has run, the label is //ncore_example:convert; the :convert
target name is dataset-neutral and does not change after the rename.)
--store-type itar is required (not optional). NuRec consumes .zarr.itar archive
stores; directory-format stores (.zarr/) load-fail with an assertion that surfaces on
the sequence JSON path rather than the store itself, making the root cause hard to
recognize.
When the input supplies seek_sec / duration_sec, append them as
--seek-sec=<seek_sec> --duration-sec=<duration_sec> to the bazel command above
(both flags together; input parsing already enforced both-or-neither). Omit both flags
when the input omits the fields.
If bazel run fails with ModuleNotFoundError, the missing package is not in the Bazel
pip graph. Do not fall back to system Python -- add the dependency to Bazel instead:
- Append the missing package to
deps/pip/requirements_3_X.in(whichever Python the converter is currently pinned to). - Regenerate the lockfile:
bazel run //deps/pip:requirements - Add
requirement("package-name")to the converter'sBUILD.bazeldeps. - Retry
bazel run //ncore_<dataset>:convert -- ...
If lockfile resolution fails (No matching distribution, conflicting transitive pins,
build wheel exited with 1 on a transitive dep): do not keep retrying version pins.
Consider whether the failure is fixable by bumping python_version per the
Python-bump rule (e.g. the reader requires a Python ABI the template doesn't currently
ship). If so, bump and retry. Otherwise, step back to the dependency-strategy
ladder and pick the next option (Option 1 → 2 → 3 → 4); update dependency_strategy in
inferred_parameters and record the reason the previous option was unreachable in
notes.
Verify output
- FILL IN check (mandatory): run
grep -rn "FILL IN" $ncore_converter_dir/ncore_*/. This must return no matches. If any remain, go back to filling in the skeleton and resolve them. - Check the output directory contains the sequence directory and
{sequence_id}.jsonmeta file. - The platform self-verification regression test (
ncore_template/tests/ncore_example_test.py) is not materialized into the converter workdir (rsync --exclude='tests/'). It runs only in the platform CI against the placeholder. The converter workdir has notests/directory by design; do not attempt to runbazel testfrom inside it. - Justifications validator (mandatory): write the full output summary (including
critical_parameter_justifications) to a temporary file and runcd "$NUREC_ONBOARD_DIR" && bazel run //skills/nurec-onboard/validators:build_ncore_converter_validator -- <summary.yaml> --store <sequence_meta>. The validator asserts every required parameter from the critical-parameter justification step is present with non-emptyparameter,value,evidence, andwrong_value_consequencefields, and that no field contains a placeholder (FILL IN,TODO,TBD,[ ... ], etc.).--store <sequence_meta>additionally verifies everyworked_exampleblocks against the converted NCore store (single-ray LiDAR prediction forT_lidar_rig/spinning_lidar_model_frame_choice; per-camera rotation + conditionally-mandatory translation prediction forT_camera_rig; per-camera projection samples forcamera_model_family; cuboid counts and sampled source tracks forsequence_frame_range_decision). Without--storethe worked-example blocks are checked for structure only, and any author-computed geometric or projection prediction would land unverified -- the convert step has just produced the sequence JSON, so always pass it. For.itarstores, pass the{sequence_id}.jsonsequence meta path, not the output directory or sequence subdirectory; directory-format stores follow the same sequence-meta entry point.- Exit 0 -> verification passed; proceed to emit the output summary.
- Exit 1 -> one or more required parameters is missing or incomplete, OR a
worked-example prediction failed the store check. You MUST emit
status: partialand list every diagnostic verbatim innotes. Do not attempt to silently drop or rename parameters to pass the check -- the required list is normative. - Exit 2 -> the summary is malformed YAML. Fix the YAML before returning.
Output
Return a structured summary:
mode: scaffold
ncore_converter_dir: <string>
output_data_path: <string>
sequence_meta: <path to .json>
inferred_parameters: { ... }
critical_parameter_justifications: [...] # from the critical-parameter justification step -- must be present
fill_in_remaining: 0 # grep "FILL IN" match count -- must be 0
status: success | partial
notes: [<string>]Step attempt exit anchor (scaffold mode): capture
runs[*].ended_athere, aftervalidators/build_ncore_converter_validator.pyreturns (or afterstatus: partialis written). Computeduration_sec.
3. Fix Mode
Step attempt entry anchor (fix mode): capture
runs[*].started_athere, before reading the diagnosis. Each fix-mode invocation is its ownruns[*]entry, not a continuation.
Parse diagnosis
- Parse input: extract
ncore_converter_dir,diagnosis.source,diagnosis.errors,diagnosis.metrics,diagnosis.suggested_fixes. - Read the converter source code in
$ncore_converter_dirto understand the current implementation.
Apply fixes
For each error/suggestion in the diagnosis:
- Map the error to a specific converter function using the suggested fixes and
../validate-ncore-data/common-failures.mdpatterns. - Read the relevant converter code section.
- Apply the targeted fix.
- If multiple fixes are needed, apply them all before re-running.
Re-run conversion
cd $ncore_converter_dir && bazel run //ncore_<dataset>:convert -- \
--root-dir=<data.path> \
--output-dir=<ncore_output_dir> \
[--seek-sec=<seek_sec> --duration-sec=<duration_sec>] \
<subcommand> --store-type itarForward --seek-sec / --duration-sec whenever the original input supplied
them (Scaffold-mode converter-run semantics apply unchanged in fix mode).
Verify and test
- FILL IN check: run
grep -rn "FILL IN" $ncore_converter_dir/ncore_*/. Must return no matches. - The converter workdir has no in-tree test directory (
rsync --exclude='tests/'strips the platform's placeholder regression test). Validation is performed by the platform validator binary; invoke it from$NUREC_ONBOARD_DIRper the validate-ncore-data step. - Justifications validator: if any critical parameter was changed by a fix, re-run
cd "$NUREC_ONBOARD_DIR" && bazel run //skills/nurec-onboard/validators:build_ncore_converter_validator -- <summary.yaml> --store <sequence_meta>on the updated summary (see Scaffold Mode output's Justifications validator for the exact semantics). The re-converted sequence meta JSON is the input to--store, so any worked-example geometric prediction whose value drifted with the fix is caught here. Exit 0 is required to proceed; any other exit code forcesstatus: partial.
Output
Return a structured summary:
mode: fix
ncore_converter_dir: <string>
output_data_path: <string>
sequence_meta: <path to .json>
diagnosis_source: <string>
fixes_applied: [<string>]
critical_parameter_justifications: [...] # re-justify any critical params that were changed by a fix
fill_in_remaining: 0
status: success | partial
notes: [<string>]Step attempt exit anchor (fix mode): capture
runs[*].ended_athere, after smoke tests pass and the justifications validator (if re-run) returns. Computeduration_sec.
4. Camera Model Quick Reference
| Model | NCore class | Key parameters |
| Pinhole | OpenCVPinholeCameraModelParameters | fx, fy, cx, cy, distortion_coefficients, width, height |
| Fisheye | OpenCVFisheyeCameraModelParameters | fx, fy, cx, cy, distortion_coefficients, width, height, max_angle (compute from calibration via OpenCVFisheyeCameraModelParameters.compute_max_angle() — never from the sensor spec's declared FOV; see conventions.md "Camera model selection") |
| FTheta | FThetaCameraModelParameters | affine_transform, distortion_coefficients, width, height |
For fisheye max_angle, see
conventions.md "Camera model selection"
for the ncore.data / ncore.sensors import split and keyword-argument call
shape.
5. Constraints
- No user interaction: infer everything from the data directory and description.
- No system pip: never run
pip install. All packages go throughdeps/pip/requirements_3_X.in; all execution viabazel run. Use the dependency-strategy ladder (Options 1-4) — Option 4 is last resort. Never invoke system Python (python3 -c,python3 script.py, or any other system Python call) for code that importsncore— system Python does not have access to the Bazel-pinnednvidia-ncoreversion. For ad-hoc NCore checks, write a temporary script in the converter repo and run it withbazel run. - Validator and eval tools live in NuRec Onboard, not in the converter workdir. The shard validators (
//skills/nurec-onboard/ncore_validation:validate,//skills/nurec-onboard/ncore_validation:eval) are platform code at$NUREC_ONBOARD_DIR/ncore_validation/; they are not materialized into$ncore_converter_dirand the agent's sandbox mounts$NUREC_ONBOARD_DIRread-only. Fix the converter when validation reports a failure, not the checks. - No git writes: do not commit or push. Track original files for revert if needed.
- Bazel commands: always
cd $ncore_converter_dirfirst.
6. Additional Resources
- NCore data specification -- pose graph, coordinate frames, and transformation conventions
- NCore sensor models -- camera/LiDAR intrinsic parameter schemas
- NCore data formats -- V4 component store layout on disk
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

