Upgrading from NCore 19.x#
NCore 20 keeps the data format: data written by NCore 19.x is read by NCore 20, and data written by NCore 20 in zarr
format v2 (the default) is read by NCore 19.x. This page lists the API changes of NCore 20 relative to the latest
NCore 19.x release (19.9), by area; changes that already shipped in an earlier 19.x release are marked with that
version. The GitHub releases hold the release notes of each version,
including the changes between the pre-releases of NCore 20; the repository no longer keeps a CHANGELOG.md.
Most code reading data through SequenceLoaderV4 or the component readers keeps working;
check the sections below for the APIs you use. Common changes:
optional parameters of many APIs are keyword-only;
camera / lidar ray generation returns valid flags;
model factories are module-level functions (
ncore.sensors.camera_model_from_parameters);invalid input raises
ValueErrorinstead ofAssertionError;the storage APIs below the components are new (
ncore.data.stores).
Dependencies#
zarr-python 3 (>= 3.1.4, on Python >= 3.11) is supported next to zarr-python 2, and installed by default on Python >= 3.11. The implementation is selected at import time. See zarr Versions and Formats. On Python >= 3.11, zarr-python 2 requires >= 2.18.7 (
"zarr<3"resolves to it); older Python versions keep zarr-python 2 >= 2.12.zarr format v3 stores can be written opt-in (
zarr_format=3ofSequenceComponentGroupsWriter,--zarr-format 3of the data converters), and need zarr-python 3 for writing and reading. zarr format v2 stays the default.Python 3.8 remains supported (with zarr-python 2).
numcodecsandfsspecare declared dependencies.
Public packages#
Import public names from the public packages instead of ncore.impl:
ncore.data.stores(new): indexed tar archives, zarr hierarchy stores, groups / arrays (see Storage API (ncore.data.stores)).ncore.geometry(new):PoseInterpolator,PoseGraphInterpolator,MotionCompensator,HalfClosedInterval,time_bounds, and the rigid transformation functions (se3_inverse,so3_trans_2_se3,transform_point_cloud,bbox_pose,pose_bbox,transform_bbox,is_within_3d_bboxes; names and signatures unchanged fromncore.impl.common.transformations).ncore.data: the JSON typesJson,JsonDocument,JsonLikeandJsonDocumentLike(JsonLikewas inncore.impl.data.types),FOV,RayBundleSensorProtocol, the asynchronous protocols (AsyncSequenceLoaderProtocoland friends) andAsyncRayBundleSensorPointCloudsSourceAdapter.ncore.data.v4:BaseSensorComponentReader/BaseSensorComponentWriter,BaseRayBundleSensorComponentReader/BaseRayBundleSensorComponentWriter,SequenceMeta,ComponentGroupAssignmentsandIndexTailRetention.ncore.impl.data.v4.compatno longer re-exports the compatibility protocols (SequenceLoaderProtocol,CameraSensorProtocol, …): import them fromncore.data.ncore.data.EncodedImageHandleisCameraSensorProtocol.EncodedImageDataHandleProtocol(sameget_data()method, now runtime-checkable).
Component readers#
Arrays returned by component readers are read-only (e.g., frame data, ray bundles, timestamps, generic data, and the cached
frames_timestamps_us, which returns the same array on each access): copy them before modifying them in place (np.array(data)).All pose getters of
PosesComponent.Reader(get_static_pose/get_dynamic_poseand the plural generators) return poses with their stored dtype (float32 or float64). This is kept by design, like the read-only arrays; convert poses if a specific dtype is required. (The singular getters return the stored dtype since 19.8.1; earlier 19.x versions always returned float64.)All reads of array data have asynchronous variants (
*_async), see Asynchronous Reads.PosesComponent.validate_frame_name(name)replacesncore.impl.data.v4.components.validate_frame_nameand raisesValueError.PointCloudsComponent.Writer.store_pc/CameraLabelsComponent.Writer.store_labelandset_generic_dataof all component writers return the writer (chainable).Keyword-only arguments:
store_typeandzarr_formatofSequenceComponentGroupsWriterandSequenceComponentGroupsWriter.from_reader;attribute_schemasofPointCloudsComponent.Writer; theattributes,generic_dataandgeneric_meta_dataofstore_pcand thegeneric_meta_dataofstore_label. Arguments forwarded to writer constructors byregister_component_writerfollow itsgroup_nameandgeneric_meta_dataparameters: pass them by keyword.Errors:
PointCloudsComponent.Reader.get_attribute_schemaandCameraLabelsComponent.Reader.get_labelraiseKeyErrorfor unknown names / timestamps;register_component_writerraisesValueErrorfor empty or duplicate names; a duplicate component instance raisesRuntimeErrorwhen opening a sequence; a mismatching shape of promoted generic data raisesValueError.Invalid input to the component writers (poses, sensor frames, cuboids, point clouds, camera labels, and
finalize) and to the validated data types ofncore.data(camera / lidar model parameters,BBox3,LabelType,LabelSchema,QuantizationParams,CuboidTrackObservation,CameraLabelDescriptor) raisesValueErrorinstead ofAssertionError, also underpython -O.Custom components access their data via
self._group, ancore.data.stores.Group(instead of a zarr-python group, which is available asself._group.zarr), see Storage API (ncore.data.stores).
Opening sequences#
Optional parameters are keyword-only:
SequenceComponentGroupsReader(paths, *, open_consolidated=..., itar_index_tail_read_size=..., max_concurrent_requests=..., ...)andSequenceLoaderV4(reader, *, poses_component_group_name=..., ...). For example, replaceSequenceComponentGroupsReader(paths, False)withSequenceComponentGroupsReader(paths, open_consolidated=False).SequenceComponentGroupsReader’smax_threadsis renamed tomax_concurrent_requests(as ofopen_async): the number of threads opening the component stores.SequenceLoaderV4.open(paths, ...)/open_async(paths, ...)open the component stores and the loader in one step (the reader + loader construction keeps working).open_consolidatedaccepts"auto", andcomponent_group_pathsany sequence ofUPath/Path.A missing component group raises
KeyError, an empty path listValueError..itarpaths are no longer checked for existence up front: a missing archive raisesFileNotFoundErrorwhen its index is read.Readers release the index tail read of each
.itarstore after opening it from its consolidated metadata, so records near the end of an archive are read from storage when accessed;itar_index_tail_retention="keep"keeps the previous behaviour (see Memory of Opened Sequences).
Compatibility API (SequenceLoaderV4)#
SequenceLoaderProtocol.query_camera_labelsreturns aSequenceinstead of aList.SequenceLoaderV4.Sensor/CameraSensor/RayBundleSensor/LidarSensor/RadarSensor: all arguments after the reader are keyword-only,Sensor(sensor_reader=...)isSensor(reader, pose_graph=...),CameraSensor’smask_readerandLidarSensor’smodel_parametersdefault to None. The constructors assign the pose graph directly: subclass overrides ofset_pose_graphare not called during construction.Ray bundle sensors take an optional
motion_compensator(the loader passes its own, configured bymotion_compensator_parameters, see Motion Compensation); without one they useMotionCompensator(pose_graph), exposed by the newmotion_compensatorproperty.set_pose_graphreplaces the compensator by one of the new pose graph with the same parameters, so point clouds of a sensor with a replaced pose graph are motion-compensated with that pose graph (19.x kept compensating with the original pose graph).get_camera_sensor/get_lidar_sensor/get_radar_sensorraiseKeyErrorfor unknown sensor ids (19.x raisedValueError), like the other getters.RayBundleSensorPointCloudsSourceAdapter(sensor, *, return_index=..., promote_generic_data=...)and its asynchronous twin take their optional arguments by keyword.The
T_sensor_rigproperty of sensors (and ofSensorProtocolimplementations) is replaced byget_T_sensor_rig(rig_node="rig"): replacesensor.T_sensor_rigwithsensor.get_T_sensor_rig(). The rig frame defaults to the well-known"rig"node; useget_frames_T_source_sensor()for other transformations.RayBundleSensorProtocol.FramePointCloudhas an optionaltimestamp_usfield (the per-point timestamps, read-only); lidar / radar point-cloud sources adapted viaget_point_clouds_sourcereuse it.get_closest_frame_indexraisesValueErrorfor an out-of-rangerelative_frame_time.
Storage#
The storage APIs below the components were rewritten (ncore.data.stores, see Storage API (ncore.data.stores)):
IndexedTarStoreis replaced byIndexedTarArchive(the records of an archive, independent of zarr-python) andIndexedTarZarrStore(a zarr hierarchy in an archive). Other zarr-python stores are used viaZarrStoreAdapter(e.g.,ZarrStoreAdapter.directory(path)). AnIndexedTarZarrStoreis not a zarr-python store itself: passstore.zarrto zarr-python, or open the hierarchy viastore.open_root_group().Removed:
ConsolidatedCompressedMetadataStore, themetadata_key=/mode=/**kwargsarguments of the consolidation functions,IndexedTarStore.mutex/.index/.TarRecord/.TailBuffer. The records of an archive areIndexedTarArchive.records(TarRecord.offset_dataisRecord.offset).consolidate_compressed_metadata/open_compressed_consolidatedare replaced byStore.consolidate()/Store.open_root_group();Store.is_consolidated_metadata_key(key)identifies consolidated metadata records.Optional parameters are keyword-only, e.g.
IndexedTarZarrStore(path, mode="w")instead ofIndexedTarZarrStore(path, "w"), andopen_root_group(consolidated=False).Writes through hierarchies opened for reading raise
ValueError, alsoStore.create_root_groupandStore.consolidateof stores opened for reading.Group.require_groupof an existing array raisesValueError.Opening consolidated metadata of an unsupported format raises
ValueError(19.x raised zarr-python’sMetadataError).Node metadata records of
.itararchives are appended when closing an archive, so archives are not byte-identical to archives written by NCore 19.8 (their records are), and NCore 19.8 reads them.
Sensor models#
CameraModel.from_parameters(...)is removed: usencore.sensors.camera_model_from_parameters(...). LikewiseExternalDistortionModel.from_parameters->external_distortion_model_from_parameters, andLidarModel.maybe_from_parameters/StructuredLidarModel.maybe_from_parameters->maybe_lidar_model_from_parameters(orlidar_model_from_parameters; checkisinstance(model, StructuredLidarModel)where a structured model is required). The factories forward extra keyword arguments to the model constructor (e.g.newton_iterations=...), and factories registered withregister_*_modelreceive them as**model_kwargs.Ray generation returns valid flags (see Ray Validity):
image_points_to_camera_rays/pixels_to_camera_raysreturn aCameraModel.CameraRaysReturn(use.camera_rays, mask with.valid_flag) instead of a tensor.camera_rays=of the world-ray unprojections takes aCameraRaysReturn(CameraRaysReturn.all_valid(rays)for rays known to be valid), andCameraModel.WorldRaysReturnhas avalid_flagfield. Camera models implementing_image_points_to_camera_rays_implreturn aCameraRaysReturn.StructuredLidarModel.elements_to_sensor_raysreturnsLidarModel.SensorRaysReturn(.sensor_rays),elements_to_sensor_pointsreturnsLidarModel.SensorPointsReturn(.sensor_points), andelements_to_sensor_anglesreturnsLidarModel.SensorAnglesReturn(.sensor_angles; custom structured models return it).sensor_rays=ofelements_to_world_rays_shutter_posetakes aSensorRaysReturn, andLidarModel.WorldRaysReturnhas avalid_flagfield.LidarModel.SensorRayReturnis renamedLidarModel.SensorRaysReturn.sensor_rays_to_sensor_anglesalso accepts aSensorRaysReturn(custom lidar models implementing it should accept that type).WorldPointsToImagePointsReturn,WorldPointsToPixelsReturnandWorldPointsToSensorAnglesReturnhave a requiredvalid_flagfield over all input points.valid_indicesare always 1-D (since 19.8.6; earlier 19.x versions returned a 0-dim tensor when exactly one point projected).
Keyword-only arguments: the
return_*flags of allworld_points_to_*methods;camera_rays,return_T_sensor_worldsandreturn_timestampsof thepixels_to_world_rays_*/image_points_to_world_rays_*methods, andsensor_rays,return_T_sensor_worldsandreturn_timestampsofelements_to_world_rays_shutter_pose(e.g., replacepixels_to_world_rays_static_pose(pixels, T, ts, rays)withpixels_to_world_rays_static_pose(pixels, T, ts, camera_rays=rays)); the model arguments afterparameters, device, dtype(newton_iterations,min_2d_norm,max_normalized_radius_squared,tangential_iterations); forRowOffsetStructuredSpinningLidarModel,deviceanddtypenow directly follow the parameters, and theangles_to_columns_map_*/fov_eps_factorarguments are keyword-only.camera_rays_to_image_points(cam_rays=...)/camera_rays_to_pixels(cam_rays=...)are renamedcamera_rays=; subclasses overriding_camera_rays_to_image_points_implshould rename the parameter.OpenCV pinhole: validity follows the first extremum of the radial distortion instead of fixed limits of the distortion factor (override with
max_normalized_radius_squared=, see Ray Validity), and the undistortion iterates until every point converged, so image points near the image corners stay valid when unprojected with central points.OpenCVPinholeCameraModel.compute_max_normalized_radius_squaredisOpenCVPinholeCameraModelParameters.compute_max_normalized_radius_squared.OpenCV fisheye:
inverse_max_angleis private. (Since 19.8.4, the inverse is bracketed on the increasing branch of the polynomial, andnewton_iterationsis an upper bound with default 20 instead of 3.)FTheta:
FThetaCameraModeltakes a keyword-onlytangential_iterationsargument (an attribute in 19.9), and itstangential_coeffsbuffer is persistent: state dicts contain it (load state dicts written by NCore 20 into older versions withstrict=False). (FThetaCameraModelParameters.tangential_coeffswere added in 19.9.0: default zeros, omitted when stored as zeros, non-zero coefficients requiremax_angle < pi/2, readers older than 19.9 ignore them.)Private hooks for subclasses:
_has_tangentials/_has_tangential->_has_tangential_distortion,_has_thin_prism->_has_thin_prism_distortion; the OpenCV pinhole hooks_compute_distortion/_iterative_undistortare single-underscore methods. The undistortion stop parameterstop_mean_of_squares_error_px2is the keyword-onlystop_squared_residual, which applies per point (instead of to the mean over all points).Invalid input to the camera and lidar models (constructor arguments, shapes and dtypes of poses / points / image points / elements, missing or reversed timestamps with
return_timestamps=True, …) raisesValueErrorinstead ofAssertionError, also for rays passed for reuse (camera_rays=/sensor_rays=) that don’t match the input points. The constructors validatenewton_iterations(FTheta, OpenCV fisheye) andangles_to_columns_map_dtype(row-offset spinning lidar), which were checked on first use.RowOffsetStructuredSpinningLidarModelParametersrejects column azimuths one full revolution or more away from the first column.Rectificator’svalid_maskalso requires a valid ray of the target camera.
Geometry#
MotionCompensator.motion_decompensate_points(...)returns aMotionCompensator.MotionDecompensationResult: replacexyz = mc.motion_decompensate_points(...)withxyz = mc.motion_decompensate_points(...).xyz_pointtime.MotionCompensator.Parametersselects the motion compensation method (EXACT, the default, or the fasterINTERPOLATED), see Motion Compensation.PoseInterpolator.slerp,.f_tand.last_roware private: useinterpolate_to_timestamps/extrapolate_to_timestamps(posesandtimestampsremain public). Interpolation accepts any strictly increasing time domain; extrapolation requires integer microseconds.MotionCompensator(pose_graph, *, parameters=...):parameters(new) is keyword-only, and so arereference_timestamp_usandanchor_frame_idofmotion_compensate_points/motion_decompensate_points(e.g., replacemc.motion_compensate_points(sensor_id, xyz, ts, start, end, ref)withmc.motion_compensate_points(sensor_id, xyz, ts, start, end, reference_timestamp_us=ref)).time_bounds,HalfClosedInterval,PoseInterpolator,is_within_3d_bboxes,MotionCompensator.motion_compensate_points/motion_decompensate_pointsandPoseGraphInterpolator.EdgeraiseValueErrorinstead ofAssertionErrorfor invalid input.
Data converters#
BaseDataConverterConfig.zarr_format(default 2) selects the zarr format of the written stores (--zarr-formatof the converter CLIs). On Python < 3.10, fields added by subclasses ofBaseDataConverterConfigneed defaults.