Skip to content

v20.0.0-beta.6

Pre-release
Pre-release

Choose a tag to compare

@github-actions github-actions released this 17 Nov 11:15
Immutable release. Only release title and notes can be modified.

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 / KeyError with messages naming the expected and given value, instead of assert (which python -O removes).
  • Opening sequences: the new SequenceLoaderV4.open() opens a sequence in one synchronous call; ray bundle sensors get default motion compensators that follow set_pose_graph; get_T_sensor_rig(rig_node="rig") replaces the T_sensor_rig property.
  • 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_range no 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: use Group.keys(). keys(), items(), iteration, groups() and the new arrays() are ordered by name with both zarr-python versions.
  • Group(group, cache, store): cache and store are keyword-only.
  • Store.open_root_group(consolidated=...): consolidated is keyword-only; the store records whether the hierarchy was opened from consolidated metadata.
  • IndexedTarZarrStore.release_index_tail(retention) no longer takes consolidated: it uses the flag of the last open_root_group (before any opening: releases as for an unconsolidated hierarchy).
  • Store can no longer be constructed directly (TypeError): wrap zarr-python stores with ZarrStoreAdapter.
  • IndexedTarArchive(path, *, ...), IndexedTarZarrStore(path, *, ...) and their open_async: all parameters after the path are keyword-only.
  • Every write method (create_group, require_group, create_array, create_bytes_array, update_attrs, ...) raises ValueError on hierarchies opened for reading, before writing, with both zarr-python versions (also require_group of an existing group), and so do Store.create_root_group / Store.consolidate of stores opened for reading; previously some writes raised zarr-python errors (e.g. ReadOnlyError).
  • Group.require_group of an existing array raises ValueError (was zarr-python 2's ContainsArrayError, zarr-python 3's TypeError).
  • zarr-python 2: consolidated metadata of an unsupported format raises ValueError (was zarr.errors.MetadataError).
  • New: Group.arrays(), attr_float() / attr_bool(), Array.chunks / fill_value / ndim, require_group(..., attributes=...), optional create_root_group attributes, DEFAULT_INDEX_TAIL_READ_SIZE, prefetch_keys taking any sequence.
  • New exports: ZarrStore (runtime: the installed zarr-python's store base class, was object), NodeCache, IndexTailRetention, ZarrFormat, Selection, FillValue, Attributes, BloscCname, BloscShuffle.

Opening sequences / V4 components (ncore.data.v4)

  • SequenceComponentGroupsReader(paths, *, ...) and its open_async, SequenceLoaderV4(reader, *, ...) and SequenceLoaderV4.open_async(paths, *, ...): optional parameters are keyword-only (a positional max_threads was previously bound to the index tail retention).
  • SequenceComponentGroupsReader's max_threads is renamed max_concurrent_requests (as of open_async: the size of its thread pool, positive or None).
  • New SequenceLoaderV4.open(paths, *, ...): synchronous counterpart of open_async with the same parameters. Readers and both openers accept open_consolidated="auto" and any sequence of paths.
  • Missing component group -> KeyError; empty path list -> ValueError; duplicate component instances when opening -> RuntimeError; empty or duplicate register_component_writer name -> ValueError; mismatching promoted generic data shape -> ValueError (all were AssertionError).
  • PointCloudsComponent.Reader.get_attribute_schema (unknown attribute) and CameraLabelsComponent.Reader.get_label (unknown timestamp) raise KeyError.
  • PointCloudsComponent.Writer.store_pc, CameraLabelsComponent.Writer.store_label and set_generic_data of all component writers return the writer (were None).
  • Keyword-only: store_type / zarr_format of SequenceComponentGroupsWriter(...) and SequenceComponentGroupsWriter.from_reader(...); attribute_schemas of PointCloudsComponent.Writer; attributes / generic_data / generic_meta_data of store_pc; generic_meta_data of store_label. Writer arguments passed through register_component_writer follow its group_name / generic_meta_data: pass them by keyword.
  • ncore.impl.data.v4.components.validate_frame_name -> PosesComponent.validate_frame_name (raises ValueError).
  • Invalid input to the component writers (poses, camera / lidar / radar sensors, cuboids, point clouds, camera labels, finalize) and to the validated data types of ncore.data (camera / lidar model parameters, BBox3, LabelType, LabelSchema, QuantizationParams, CuboidTrackObservation, CameraLabelDescriptor) raises ValueError instead of AssertionError, also under python -O.
  • BaseSensorComponentReader.frames_timestamps_us returns 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=...) is Sensor(reader, ...); CameraSensor.mask_reader and LidarSensor.model_parameters default to None.
  • The constructors assign the pose graph directly: subclass overrides of set_pose_graph aren't called during construction.
  • RayBundleSensor.motion_compensator is optional (default MotionCompensator(pose_graph)) and exposed as a property. set_pose_graph replaces the compensator (also a passed one, e.g. the loader's) by MotionCompensator(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_sensor raise KeyError for unknown sensor ids (was ValueError).
  • RayBundleSensorPointCloudsSourceAdapter(sensor, *, return_index, promote_generic_data) and AsyncRayBundleSensorPointCloudsSourceAdapter: optional arguments are keyword-only.
  • The T_sensor_rig property is replaced by get_T_sensor_rig(rig_node="rig") (also for SensorProtocol implementations): sensor.T_sensor_rig -> sensor.get_T_sensor_rig(). The rig frame defaults to the well-known "rig" node.
  • RayBundleSensorProtocol.FramePointCloud has an optional read-only timestamp_us field; adapted lidar / radar point clouds reuse it as their timestamp_us attribute.
  • get_closest_frame_index raises ValueError for relative_frame_time outside [0, 1].
  • ncore.data.EncodedImageHandle is CameraSensorProtocol.EncodedImageDataHandleProtocol (runtime-checkable); the separate protocol in ncore.impl.data.types is 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. Use camera_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_rays renamed camera_rays.
  • WorldPointsToImagePointsReturn, WorldPointsToPixelsReturn, WorldPointsToSensorAnglesReturn have a required valid_flag over all input points; the return_* flags of world_points_to_* are keyword-only.
  • Keyword-only: camera_rays / return_T_sensor_worlds / return_timestamps of the camera pixels_to_world_rays_* / image_points_to_world_rays_* methods, and sensor_rays / return_T_sensor_worlds / return_timestamps of the lidar elements_to_world_rays_shutter_pose.
  • StructuredLidarModel.elements_to_sensor_angles returns a SensorAnglesReturn (was a tensor; custom structured models must return one); sensor_rays_to_sensor_angles accepts a SensorRaysReturn and combines its valid flag (custom lidar models must accept it).
  • Keyword-only model arguments: FThetaCameraModel / OpenCVFisheyeCameraModel (newton_iterations, min_2d_norm, and FTheta's new tangential_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 / dtype moved directly after parameters.
  • FTheta tangential_coeffs buffer is persistent (older state dicts still load; new ones need strict=False in 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 parameter stop_mean_of_squares_error_px2 is the keyword-only stop_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, and camera_rays= / sensor_rays= passed for reuse that don't match the input points) raises ValueError instead of AssertionError, also under python -O. The constructors validate newton_iterations >= 0 (FTheta, OpenCV fisheye) and angles_to_columns_map_dtype (row-offset spinning lidar: an integer type holding the largest column index), previously checked on first use.
  • RowOffsetStructuredSpinningLidarModelParameters rejects 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_points returns a MotionCompensator.MotionDecompensationResult: use .xyz_pointtime.
  • PoseInterpolator.slerp, f_t, last_row are private (use interpolate_to_timestamps / extrapolate_to_timestamps); the constructor (and in_range) take array-like poses / timestamps. Interpolation accepts any strictly increasing time domain, extrapolation requires integer microseconds.
  • MotionCompensator(pose_graph, *, parameters): parameters is keyword-only, as are reference_timestamp_us / anchor_frame_id of motion_compensate_points / motion_decompensate_points.
  • time_bounds, HalfClosedInterval, PoseInterpolator, is_within_3d_bboxes, MotionCompensator.motion_compensate_points / motion_decompensate_points, PoseGraphInterpolator.Edge raise ValueError instead of AssertionError.

Data converters

  • BaseDataConverterConfig.zarr_format defaults to 2. On Python < 3.10, fields added by subclasses of BaseDataConverterConfig need defaults. FileBasedDataConverterConfig.root_dir is still required (validated after construction).

Packaging

  • numcodecs and fsspec are declared dependencies.
  • zarr: Python >= 3.11 -> zarr-python 2 >= 2.18.7 or zarr-python 3 >= 3.1.4 (zarr<3 resolves to >= 2.18.7 there); Python < 3.11 -> zarr-python 2 >= 2.12, < 3.
  • ATTRIBUTIONS.md lists 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

  • (wheel) declare numcodecs and fsspec, pin zarr per Python version (b596c6e) - @janickm

🔧 Chore

  • map Dezhen Lu (0z5a) to his GitHub username in release notes (fefbe37) - @janickm
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

⚙️ CI

🏗️ Build

🎨 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