Highlights
Sixth beta of NCore 20 and the API freeze candidate before rc.1: the public APIs get their final shape (keyword-only optional parameters, complete public exports, ValueError instead of assert for invalid input), with a new guide for upgrading from NCore 19.x. Install with pip install --pre nvidia-ncore or nvidia-ncore==20.0.0b6.
- API freeze preparation: optional parameters of the storage, loader and sensor model APIs are keyword-only, and the public packages (
ncore.data,ncore.data.v4,ncore.data.stores,ncore.geometry,ncore.sensors) export every type their APIs take and return; the bundled tools use only the public packages. - Validation: invalid user input raises
ValueError/KeyErrorwith messages naming the expected and given value, instead ofassert(whichpython -Oremoves). - Opening sequences: the new
SequenceLoaderV4.open()opens a sequence in one synchronous call; ray bundle sensors get default motion compensators that followset_pose_graph;get_T_sensor_rig(rig_node="rig")replaces theT_sensor_rigproperty. - Sensor models: projections and lidar angle conversions return valid flags consistently; the OpenCV pinhole undistortion keeps image-corner points valid in mixed batches.
- Storage: sorted group / array listings with both zarr-python versions and uniform
ValueErrors for writes to read-only hierarchies and stores. - Fix:
HalfClosedInterval.cover_rangeno longer includes samples outside the interval (e.g. a last sample equal to the exclusive stop). - Documentation: new Upgrading from NCore 19.x guide, and documentation on ray validity, motion compensation and the storage API.
New contributors
Thanks to Dezhen Lu (@0z5a) for their first contribution, finding and fixing the HalfClosedInterval.cover_range bounds (#264)!
Upgrading from beta.5
Storage (ncore.data.stores)
Group.members()is removed: useGroup.keys().keys(),items(), iteration,groups()and the newarrays()are ordered by name with both zarr-python versions.Group(group, cache, store):cacheandstoreare keyword-only.Store.open_root_group(consolidated=...):consolidatedis keyword-only; the store records whether the hierarchy was opened from consolidated metadata.IndexedTarZarrStore.release_index_tail(retention)no longer takesconsolidated: it uses the flag of the lastopen_root_group(before any opening: releases as for an unconsolidated hierarchy).Storecan no longer be constructed directly (TypeError): wrap zarr-python stores withZarrStoreAdapter.IndexedTarArchive(path, *, ...),IndexedTarZarrStore(path, *, ...)and theiropen_async: all parameters after the path are keyword-only.- Every write method (
create_group,require_group,create_array,create_bytes_array,update_attrs, ...) raisesValueErroron hierarchies opened for reading, before writing, with both zarr-python versions (alsorequire_groupof an existing group), and so doStore.create_root_group/Store.consolidateof stores opened for reading; previously some writes raised zarr-python errors (e.g.ReadOnlyError). Group.require_groupof an existing array raisesValueError(was zarr-python 2'sContainsArrayError, zarr-python 3'sTypeError).- zarr-python 2: consolidated metadata of an unsupported format raises
ValueError(waszarr.errors.MetadataError). - New:
Group.arrays(),attr_float()/attr_bool(),Array.chunks/fill_value/ndim,require_group(..., attributes=...), optionalcreate_root_groupattributes,DEFAULT_INDEX_TAIL_READ_SIZE,prefetch_keystaking any sequence. - New exports:
ZarrStore(runtime: the installed zarr-python's store base class, wasobject),NodeCache,IndexTailRetention,ZarrFormat,Selection,FillValue,Attributes,BloscCname,BloscShuffle.
Opening sequences / V4 components (ncore.data.v4)
SequenceComponentGroupsReader(paths, *, ...)and itsopen_async,SequenceLoaderV4(reader, *, ...)andSequenceLoaderV4.open_async(paths, *, ...): optional parameters are keyword-only (a positionalmax_threadswas previously bound to the index tail retention).SequenceComponentGroupsReader'smax_threadsis renamedmax_concurrent_requests(as ofopen_async: the size of its thread pool, positive or None).- New
SequenceLoaderV4.open(paths, *, ...): synchronous counterpart ofopen_asyncwith the same parameters. Readers and both openers acceptopen_consolidated="auto"and any sequence of paths. - Missing component group ->
KeyError; empty path list ->ValueError; duplicate component instances when opening ->RuntimeError; empty or duplicateregister_component_writername ->ValueError; mismatching promoted generic data shape ->ValueError(all wereAssertionError). PointCloudsComponent.Reader.get_attribute_schema(unknown attribute) andCameraLabelsComponent.Reader.get_label(unknown timestamp) raiseKeyError.PointCloudsComponent.Writer.store_pc,CameraLabelsComponent.Writer.store_labelandset_generic_dataof all component writers return the writer (wereNone).- Keyword-only:
store_type/zarr_formatofSequenceComponentGroupsWriter(...)andSequenceComponentGroupsWriter.from_reader(...);attribute_schemasofPointCloudsComponent.Writer;attributes/generic_data/generic_meta_dataofstore_pc;generic_meta_dataofstore_label. Writer arguments passed throughregister_component_writerfollow itsgroup_name/generic_meta_data: pass them by keyword. ncore.impl.data.v4.components.validate_frame_name->PosesComponent.validate_frame_name(raisesValueError).- Invalid input to the component writers (poses, camera / lidar / radar sensors, cuboids, point clouds, camera labels,
finalize) and to the validated data types ofncore.data(camera / lidar model parameters,BBox3,LabelType,LabelSchema,QuantizationParams,CuboidTrackObservation,CameraLabelDescriptor) raisesValueErrorinstead ofAssertionError, also underpython -O. BaseSensorComponentReader.frames_timestamps_usreturns the same cached read-only array on every access.- New exports: the base sensor / ray bundle component readers and writers,
IndexTailRetention.
Compatibility API (SequenceLoaderV4 sensors)
Sensor,CameraSensor,RayBundleSensor,LidarSensor,RadarSensor: reader positional, everything else keyword-only;Sensor(sensor_reader=...)isSensor(reader, ...);CameraSensor.mask_readerandLidarSensor.model_parametersdefault toNone.- The constructors assign the pose graph directly: subclass overrides of
set_pose_grapharen't called during construction. RayBundleSensor.motion_compensatoris optional (defaultMotionCompensator(pose_graph)) and exposed as a property.set_pose_graphreplaces the compensator (also a passed one, e.g. the loader's) byMotionCompensator(new_pose_graph, parameters=<same parameters>): point clouds of a sensor with a replaced pose graph are compensated with that pose graph (beta.5 and 19.x kept the loader's / original pose graph).get_camera_sensor/get_lidar_sensor/get_radar_sensorraiseKeyErrorfor unknown sensor ids (wasValueError).RayBundleSensorPointCloudsSourceAdapter(sensor, *, return_index, promote_generic_data)andAsyncRayBundleSensorPointCloudsSourceAdapter: optional arguments are keyword-only.- The
T_sensor_rigproperty is replaced byget_T_sensor_rig(rig_node="rig")(also forSensorProtocolimplementations):sensor.T_sensor_rig->sensor.get_T_sensor_rig(). The rig frame defaults to the well-known"rig"node. RayBundleSensorProtocol.FramePointCloudhas an optional read-onlytimestamp_usfield; adapted lidar / radar point clouds reuse it as theirtimestamp_usattribute.get_closest_frame_indexraisesValueErrorforrelative_frame_timeoutside [0, 1].ncore.data.EncodedImageHandleisCameraSensorProtocol.EncodedImageDataHandleProtocol(runtime-checkable); the separate protocol inncore.impl.data.typesis removed.- New exports in
ncore.data:RayBundleSensorProtocol,AsyncRayBundleSensorPointCloudsSourceAdapter,FOV.
Sensor models (ncore.sensors)
- Removed deprecated factories:
CameraModel.from_parameters,ExternalDistortionModel.from_parameters,LidarModel.maybe_from_parameters,StructuredLidarModel.maybe_from_parameters. Usecamera_model_from_parameters,external_distortion_model_from_parameters,maybe_lidar_model_from_parameters/lidar_model_from_parameters; the factories forward keyword arguments to the model constructors. OpenCVPinholeCameraModel.compute_max_normalized_radius_squared->OpenCVPinholeCameraModelParameters.compute_max_normalized_radius_squared.camera_rays_to_image_points(cam_rays=...)/camera_rays_to_pixels(cam_rays=...)/_camera_rays_to_image_points_impl:cam_raysrenamedcamera_rays.WorldPointsToImagePointsReturn,WorldPointsToPixelsReturn,WorldPointsToSensorAnglesReturnhave a requiredvalid_flagover all input points; thereturn_*flags ofworld_points_to_*are keyword-only.- Keyword-only:
camera_rays/return_T_sensor_worlds/return_timestampsof the camerapixels_to_world_rays_*/image_points_to_world_rays_*methods, andsensor_rays/return_T_sensor_worlds/return_timestampsof the lidarelements_to_world_rays_shutter_pose. StructuredLidarModel.elements_to_sensor_anglesreturns aSensorAnglesReturn(was a tensor; custom structured models must return one);sensor_rays_to_sensor_anglesaccepts aSensorRaysReturnand combines its valid flag (custom lidar models must accept it).- Keyword-only model arguments:
FThetaCameraModel/OpenCVFisheyeCameraModel(newton_iterations,min_2d_norm, and FTheta's newtangential_iterations, previously an attribute),OpenCVPinholeCameraModel(max_normalized_radius_squared). RowOffsetStructuredSpinningLidarModel(parameters, device, dtype, *, angles_to_columns_map_resolution_factor, angles_to_columns_map_dtype, angles_to_columns_map_init, fov_eps_factor):device/dtypemoved directly afterparameters.- FTheta
tangential_coeffsbuffer is persistent (older state dicts still load; new ones needstrict=Falsein older versions). - Private renames:
OpenCVFisheyeCameraModel.inverse_max_angle->_inverse_max_angle;_has_tangentials/_has_tangential->_has_tangential_distortion,_has_thin_prism->_has_thin_prism_distortion; OpenCV pinhole__compute_distortion/__iterative_undistort->_compute_distortion/_iterative_undistort(the stop parameterstop_mean_of_squares_error_px2is the keyword-onlystop_squared_residual, applied per point instead of to the mean). - Invalid input to camera / lidar model constructors and projection / unprojection methods (incl. missing timestamps with
return_timestamps=True, andcamera_rays=/sensor_rays=passed for reuse that don't match the input points) raisesValueErrorinstead ofAssertionError, also underpython -O. The constructors validatenewton_iterations >= 0(FTheta, OpenCV fisheye) andangles_to_columns_map_dtype(row-offset spinning lidar: an integer type holding the largest column index), previously checked on first use. RowOffsetStructuredSpinningLidarModelParametersrejects column azimuths a full revolution or more from the first column (the check previously tested the row flag).- Fix: OpenCV pinhole undistortion iterates until every point converged, so points near the image corners stay valid when unprojected together with central points.
Geometry (ncore.geometry)
MotionCompensator.motion_decompensate_pointsreturns aMotionCompensator.MotionDecompensationResult: use.xyz_pointtime.PoseInterpolator.slerp,f_t,last_roware private (useinterpolate_to_timestamps/extrapolate_to_timestamps); the constructor (andin_range) take array-like poses / timestamps. Interpolation accepts any strictly increasing time domain, extrapolation requires integer microseconds.MotionCompensator(pose_graph, *, parameters):parametersis keyword-only, as arereference_timestamp_us/anchor_frame_idofmotion_compensate_points/motion_decompensate_points.time_bounds,HalfClosedInterval,PoseInterpolator,is_within_3d_bboxes,MotionCompensator.motion_compensate_points/motion_decompensate_points,PoseGraphInterpolator.EdgeraiseValueErrorinstead ofAssertionError.
Data converters
BaseDataConverterConfig.zarr_formatdefaults to 2. On Python < 3.10, fields added by subclasses ofBaseDataConverterConfigneed defaults.FileBasedDataConverterConfig.root_diris still required (validated after construction).
Packaging
numcodecsandfsspecare declared dependencies.- zarr: Python >= 3.11 -> zarr-python 2 >= 2.18.7 or zarr-python 3 >= 3.1.4 (
zarr<3resolves to >= 2.18.7 there); Python < 3.11 -> zarr-python 2 >= 2.12, < 3. ATTRIBUTIONS.mdlists numcodecs (MIT) and fsspec (BSD-3-Clause).
Changes since v20.0.0-beta.5
➕ Added
- (data_converter) default zarr format 2 (0d9137a) - @janickm
- BREAKING (data) sync loader opening, default motion compensators and V4 component API consistency (68391b9) - @janickm
- BREAKING (sensors) factory-only model construction, uniform validity returns and camera model conventions (fbf9400) - @janickm
- BREAKING (data) uniform write checks, release_index_tail without consolidated, and Group / Array API consistency (1347a09) - @janickm
- BREAKING keyword-only optional parameters and public types of the storage, loader and sensor APIs (9a5a639) - @janickm
🪲 Fixed
- (geometry) exclude samples outside the interval from HalfClosedInterval.cover_range (0d1d0d9) - @0z5a
- BREAKING (sensors,geometry) raise ValueError instead of AssertionError in user-facing validation (0a1c2a7) - @janickm
- BREAKING (data) raise ValueError instead of AssertionError in V4 writer validation (bc1b114) - @janickm
🔄 Changed
- (tools) import the public packages instead of ncore.impl (7007cc4) - @janickm
- BREAKING (geometry) typed pose interpolator and a result type for motion decompensation (4efd97b) - @janickm
📚 Documentation
- upgrading guide for NCore 20, ray validity, motion compensation and storage API (ec6937b) - @janickm
🏗️ Build
🔧 Chore
All changes since v19.8.0
➕ Added
- (data_converter) default zarr format 2 (0d9137a) - @janickm
- BREAKING (data) sync loader opening, default motion compensators and V4 component API consistency (68391b9) - @janickm
- BREAKING (sensors) factory-only model construction, uniform validity returns and camera model conventions (fbf9400) - @janickm
- BREAKING (data) uniform write checks, release_index_tail without consolidated, and Group / Array API consistency (1347a09) - @janickm
- BREAKING keyword-only optional parameters and public types of the storage, loader and sensor APIs (9a5a639) - @janickm
- (data) export BloscCompression and EncodedArray from ncore.data.stores (bb30302) - @janickm
- (data) open hierarchies from consolidated metadata if stored (f224965) - @janickm
- (data) create arrays from chunks encoded on other threads (8fc4f14) - @janickm
- (data) create fill-valued arrays and write selections of them (d4114e8) - @janickm
- (data) read arrays into preallocated output buffers (9dc561a) - @janickm
- BREAKING (sensors) derive the OpenCV pinhole projection validity from its radial distortion (ffad25e) - @janickm
- (sensors) add FTheta tangential distortion coefficients (b7a158d) - @janickm
- public storage and geometry packages, ray validity helpers (bcd3e49) - @janickm
- BREAKING (sensors) return validity flags from structured lidar ray generation (05e6e86) - @janickm
- BREAKING (sensors) return validity flags from camera ray generation (e1b44a8) - @janickm
- (data) open sequences asynchronously (dfe3729) - @janickm
- (data) asynchronous reads of SequenceLoaderV4 (d49ca46) - @janickm
- (data) asynchronous compat protocols (d97b7ce) - @janickm
- (data) range reads of remote archives for synchronous reads (1880cb6) - @janickm
- (data) asynchronous component reader API (f67caa3) - @janickm
- BREAKING (data) zarr format v3 stores (c5fce26) - @janickm
- BREAKING (data) support zarr-python 3 (2cee604) - @janickm
- BREAKING (data) typed node API for component groups (ff2eeb0) - @janickm
🪲 Fixed
- (geometry) exclude samples outside the interval from HalfClosedInterval.cover_range (0d1d0d9) - @0z5a
- BREAKING (sensors,geometry) raise ValueError instead of AssertionError in user-facing validation (0a1c2a7) - @janickm
- BREAKING (data) raise ValueError instead of AssertionError in V4 writer validation (bc1b114) - @janickm
- (sensors) keep projection valid indices 1-D for single valid points (b47c5a0) - @nlucas-nvidia
- (sensors) apply the converged Newton step in the bracketed fisheye inverse (16d2f65) - @janickm
- (sensors) bracket the OpenCV fisheye inverse to the monotonic branch (71a0602) - @janickm
- (data) read single poses with their stored dtype (1de0192) - @janickm
- type narrowing in ncore_export_ply and the argoverse2 converter test (348262a) - @janickm
- (kitti) keep lidar point timestamps integer (5bf8f9f) - @janickm
⚡ Performance
- (geometry) add an interpolated motion compensation method (84d965b) - @janickm
- (sensors) skip zero tangential and thin-prism terms in OpenCV pinhole (2419967) - @janickm
- (sensors) skip identity linear term in FTheta camera model (1c0c1bf) - @janickm
- (data) release index tail reads of opened archives (10c2609) - @janickm
- (data) open remote indexed tar archives with a single request (f57784c) - @janickm
- (data) direct chunk reads with zarr-python 3 (979882a) - @janickm
- (data) node cache for component readers (0d6c43d) - @janickm
- (data) cache decoded label types and schemas in CameraLabelDescriptor.from_dict (1813046) - @janickm
- (data) load label and point-cloud reader data on first use (fe6eaf2) - @janickm
🔄 Changed
- (tools) import the public packages instead of ncore.impl (7007cc4) - @janickm
- BREAKING (geometry) typed pose interpolator and a result type for motion decompensation (4efd97b) - @janickm
- BREAKING (data) move is_consolidated_metadata_key to Store (5175459) - @janickm
- (sensors) construct sensor return types through their defining class (e7c26c3) - @janickm
- (data) restructure IndexedTarArchive (fd9a4f0) - @janickm
- BREAKING (data) implement IndexedTarArchive independently of zarr-python (cd3078f) - @janickm
📚 Documentation
- upgrading guide for NCore 20, ray validity, motion compensation and storage API (ec6937b) - @janickm
- remove retired skill provenance (e0e7609) - @sanchitgarg
⚙️ CI
- release notes tool in Python, commit check in build-and-test (069aee8) - @janickm
- separate the changes since the previous pre-release in release notes (3c48a54) - @janickm
- publish the documentation built by build-and-test (ed2d016) - @janickm
- refresh the Bazel disk cache on every push (09a3665) - @janickm
- remove merge queue triggers (3f52089) - @janickm
- write release notes into the release commit body (ccc650a) - @janickm
- release from main and release branches when the version changes (e8aba41) - @janickm
🏗️ Build
- (wheel) declare numcodecs and fsspec, pin zarr per Python version (b596c6e) - @janickm
- pinned cocogitto via rules_multitool (e5ca2c9) - @janickm
- don't compress the repacked patched torch wheel (dc91c12) - @janickm
- add python 3.12 / 3.13 test environments (5b5fc02) - @janickm
🎨 Style
🔧 Chore
- map Dezhen Lu (0z5a) to his GitHub username in release notes (fefbe37) - @janickm
- map Nick Lucas to his GitHub username in release notes (0a4d576) - @janickm
🧪 Tests
- (sensors) check camera ray valid flags in the unprojection tests (22db77d) - @janickm
- (sensors) share the lidar model between tests of a parameterization (c490c63) - @janickm
- run tests with a single OpenMP thread (2d4263f) - @janickm
- make tests independent of scipy / numpy versions (f2d59b0) - @janickm
Changes since v20.0.0-beta.5: v20.0.0-beta.5...v20.0.0-beta.6
Full diff: v19.8.0...v20.0.0-beta.6