API Reference

This reference contains the code documentation for modules, classes, and functions of the pix4dvortex public API. It is assumed that the user is familiar with its higher-level concepts. Some of the concepts are defined in the Concepts: Data model, algorithms, utilities, exporters and Glossary sections.

Authentication

pix4dvortex.session.is_logged_in() → bool

Check if authorization for a session has been granted. This check is independent of method of the session acquisition.

Returns:

True if authorized, False otherwise.

pix4dvortex.session.login(*, client_id, client_secret, license_key=None, name=None, hostname=None)

Request authorization for a PIX4Dengine SDK session.

Available only in authentication-enabled (Engine) builds.

Parameters:

  • client_id – oauth2 client ID.

  • client_secret – oauth2 client secret.

  • license_key – (optional) PIX4Dengine SDK license key.

  • name – (optional) Label for this session’s billing / usage activity (at most 255 characters; longer values are truncated). None or "" leaves the engine default.

  • hostname – (optional) Hostname label for billing / usage activity (at most 255 characters; longer values are truncated). None or "" omits the field.

Returns:

Device information used for license registration.

Return type:

dict

Raises:
pix4dvortex.session.logout() → bool

Log out of the current session.

Returns:

True if successful, False otherwise.

Data Model

OPF data model

For more detailed documentation of each data type, refer to OPF documentation for main dmodel types.

class pix4dvortex.dmodel.BandInformation

OPF band information.

property central_wavelength_nm
property fwhm_nm
property name
property weight
class pix4dvortex.dmodel.BaseToCanonical(self: pix4dvortex.dmodel.BaseToCanonical, *, shift: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0], scale: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [1.0, 1.0, 1.0], swap_xy: bool = False)

OPF base_to_canonical.

property scale

An internal vector used to scale coordinates to make the SRS isometric

property shift

An internal vector used to shift coordinates to center the SRS to the scene

property swap_xy

An internal boolean used to swap coordinates to get a right-handed SRS

class pix4dvortex.dmodel.CRS(self: pix4dvortex.dmodel.CRS, *, definition: str = '', geoid_height: SupportsFloat | None = None)

OPF CRS.

property definition
property geoid_height

The geoid height to be used when the vertical SRS is not supported or cannot be retrieved from WKT

class pix4dvortex.dmodel.CalibratedCamera

OPF calibrated_camera.

property id
property orientation_deg
property position
property rolling_shutter
property sensor_id
class pix4dvortex.dmodel.CalibratedCameras

OPF calibrated_cameras.

static from_dict(arg0: dict) → pix4dvortex.dmodel.CalibratedCameras
to_dict(self: pix4dvortex.dmodel.CalibratedCameras) → dict
property cameras
opf_type = 'calibrated_cameras'
property sensors
class pix4dvortex.dmodel.CalibratedControlPoint(self: pix4dvortex.dmodel.CalibratedControlPoint, id: str = '', coordinates: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0])

OPF calibrated control point.

property coordinates

The known measured (prior) 3D-position of a point in the scene.

property id

The camera ID.

class pix4dvortex.dmodel.CalibratedControlPoints(self: pix4dvortex.dmodel.CalibratedControlPoints, *, control_points: collections.abc.Sequence[pix4dvortex.dmodel.CalibratedControlPoint] = [])

OPF calibrated control points.

static from_dict(arg0: dict) → pix4dvortex.dmodel.CalibratedControlPoints
to_dict(self: pix4dvortex.dmodel.CalibratedControlPoints) → dict
property control_points

Deprecated. use points attribute instead.

property points

Collection of CalibratedControlPoint objects.

class pix4dvortex.dmodel.CalibratedITP(self: pix4dvortex.dmodel.CalibratedITP, *, id: str, coordinates: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'], calibrated_marks: collections.abc.Sequence[pix4dvortex.dmodel.MarkWithSegments])

ITP OPF extension calibrated ITP.

property calibrated_marks
property coordinates
property id
class pix4dvortex.dmodel.CalibratedIntersectionTiePoints(self: pix4dvortex.dmodel.CalibratedIntersectionTiePoints, *, points: collections.abc.Sequence[pix4dvortex.dmodel.CalibratedITP])

ITP OPF extension calibrated ITPs.

static from_dict(arg0: dict) → pix4dvortex.dmodel.CalibratedIntersectionTiePoints
hash(self: pix4dvortex.dmodel.CalibratedIntersectionTiePoints) → int
to_dict(self: pix4dvortex.dmodel.CalibratedIntersectionTiePoints) → dict
opf_type = 'ext_pix4d_calibrated_intersection_tie_points'
property points
class pix4dvortex.dmodel.CalibratedRigRelatives

OPF calibrated_rig_relatives.

property rotation_angles_deg
property translation
class pix4dvortex.dmodel.CalibratedSensor

OPF calibrated_sensor.

property id
property internals
property rig_relatives
class pix4dvortex.dmodel.Calibration(self: pix4dvortex.dmodel.Calibration, *, calibrated_cameras: pix4dvortex.dmodel.CalibratedCameras, sparse_pcl: pix4dvortex.dmodel.GLTFPointCloud | None = None, gps_bias: pix4dvortex.dmodel.GPSBias | None = None, calibrated_control_points: pix4dvortex.dmodel.CalibratedControlPoints | None = None, calibrated_itps: pix4dvortex.dmodel.CalibratedIntersectionTiePoints = None, features: pix4dvortex.dmodel.Features | None = None, matches: pix4dvortex.dmodel.Matches | None = None, original_matches: pix4dvortex.dmodel.OriginalMatches | None = None)

OPF calibration.

hash(self: pix4dvortex.dmodel.Calibration) → int

Compute the hash based on the calibrated cameras.

property calibrated_cameras
property calibrated_control_points
property calibrated_itps
property features
property gps_bias
property matches
opf_type = 'calibration'
property original_matches
property sparse_pcl
class pix4dvortex.dmodel.Camera

OPF camera.

property id
property image_orientation
property model_source
property pixel_range
property pixel_type
property sensor_id
class pix4dvortex.dmodel.CameraList

OPF camera_list.

static from_dict(arg0: dict) → pix4dvortex.dmodel.CameraList
hash(self: pix4dvortex.dmodel.CameraList) → int
to_dict(self: pix4dvortex.dmodel.CameraList) → dict
property cameras

Camera UID to image URI mapping

opf_type = 'camera_list'
property uid_generator

UID generator

class pix4dvortex.dmodel.CameraOptimizationHints

OPF camera_optimization_hints extension.

static from_dict(arg0: dict) → pix4dvortex.dmodel.CameraOptimizationHints
hash(self: pix4dvortex.dmodel.CameraOptimizationHints) → int
to_dict(self: pix4dvortex.dmodel.CameraOptimizationHints) → dict
opf_type = 'ext_pix4d_camera_optimization_hints'
class pix4dvortex.dmodel.CaptureElement

OPF capture element.

property cameras
property geolocation
property height_above_takeoff_m
property id
property orientation
property reference_camera_id
property rig_model_source
property time
class pix4dvortex.dmodel.Constraints(self: pix4dvortex.dmodel.Constraints, *, scale_constraints: collections.abc.Sequence[pix4dvortex.dmodel.ScaleConstraint] = [])

OPF calibration constraints.

Construct Constraints with a list of scale constraints.

opf_type = 'constraints'
property scale_constraints

The list of ScaleConstraints.

class pix4dvortex.dmodel.DynamicPixelRange

OPF dynamic pixel range.

property percentile
class pix4dvortex.dmodel.Edge(self: pix4dvortex.dmodel.Edge, *, v1: SupportsInt, v2: SupportsInt, confidence: SupportsFloat)

2D segment graphs OPF extension 2D edge.

property confidence
property v1
property v2
class pix4dvortex.dmodel.Features(self: pix4dvortex.dmodel.Features, *, path: os.PathLike | str | bytes)

Features OPF extension image features binary file wrapper.

hash(self: pix4dvortex.dmodel.Features) → int
opf_type = 'ext_pix4d_features'
property path
class pix4dvortex.dmodel.FisheyeInternals

OPF sensor fisheye internals.

property affine
property is_p0_zero
property is_symmetric_affine
property polynomial
property principal_point_px
type = 'fisheye'
class pix4dvortex.dmodel.GCP(self: pix4dvortex.dmodel.GCP, is_checkpoint: bool, id: str, geolocation: pix4dvortex.dmodel.Geolocation, marks: collections.abc.Sequence[pix4dvortex.dmodel.Mark] = [])

OPF GCP.

property geolocation
property id

The camera ID to reference the image.

property is_checkpoint

If true, the GCP is provided by the users for the sake of quality assessment. It will not be passed to the calibration but used later to compute the re-projection error.

property marks

The set of image points that represent the projections of a 3D-point.

class pix4dvortex.dmodel.GLTFGSplat(self: pix4dvortex.dmodel.GLTFGSplat, *, model_path: os.PathLike | str | bytes)

OPF-glTF Gaussian splatting model wrapper

copy(self: pix4dvortex.dmodel.GLTFGSplat, *, out_dir: os.PathLike | str | bytes) → pix4dvortex.dmodel.GLTFGSplat

Return a self-contained copy of this object.

Creates and returns a fully self-contained copy of this object. As a result, all managed GLTF files are copied.

Parameters:

out_dir – Directory to copy internal data files into.

Raises:

RuntimeError – if out_dir is the same as the parent of this object’s model_path().

empty(self: pix4dvortex.dmodel.GLTFGSplat) → bool
hash(self: pix4dvortex.dmodel.GLTFGSplat) → int
model_path(self: pix4dvortex.dmodel.GLTFGSplat) → pathlib.Path
size(self: pix4dvortex.dmodel.GLTFGSplat) → int
opf_type = 'ext_pix4d_gaussian_splatting'
class pix4dvortex.dmodel.GLTFPointCloud(self: pix4dvortex.dmodel.GLTFPointCloud, *, model_path: os.PathLike | str | bytes)

OPF-glTF point cloud wrapper

copy(self: pix4dvortex.dmodel.GLTFPointCloud, *, out_dir: os.PathLike | str | bytes) → pix4dvortex.dmodel.GLTFPointCloud

Return a self-contained copy of this object.

Creates and returns a fully self-contained copy of this object. As a result, all managed GLTF files are copied.

Parameters:

out_dir – Directory to copy internal data files into.

Raises:

RuntimeError – if out_dir is the same as the parent of this object’s model_path().

empty(self: pix4dvortex.dmodel.GLTFPointCloud) → bool
hash(self: pix4dvortex.dmodel.GLTFPointCloud) → int
model_path(self: pix4dvortex.dmodel.GLTFPointCloud) → pathlib.Path
size(self: pix4dvortex.dmodel.GLTFPointCloud) → int
opf_type = 'point_cloud'
class pix4dvortex.dmodel.GPSBias

OPF gps_bias.

static from_dict(*args, **kwargs)

Overloaded function.

  1. from_dict(arg0: dict) -> pix4dvortex.dmodel.GPSBias

  2. from_dict(arg0: dict) -> pix4dvortex.dmodel.GPSBias

to_dict(*args, **kwargs)

Overloaded function.

  1. to_dict(self: pix4dvortex.dmodel.GPSBias) -> dict

  2. to_dict(self: pix4dvortex.dmodel.GPSBias) -> dict

property transform
class pix4dvortex.dmodel.Geolocation(self: pix4dvortex.dmodel.Geolocation, *, crs: pix4dvortex.dmodel.CRS = pix4dvortex.dmodel.CRS(), coordinates: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0], sigmas: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0])

OPF Geolocation

property coordinates
property crs
property sigmas
class pix4dvortex.dmodel.ITP(self: pix4dvortex.dmodel.ITP, *, id: str, marks: collections.abc.Sequence[pix4dvortex.dmodel.MarkWithSegments], modified_by_user: bool = False)

ITP OPF extension ITP.

property id
property marks
property modified_by_user
class pix4dvortex.dmodel.ITPMarkCreationMethod(self: pix4dvortex.dmodel.ITPMarkCreationMethod, *, type: str = 'automatic')

ITP OPF extension mark creation method.

property type
class pix4dvortex.dmodel.InputCameras

OPF input_cameras.

static from_dict(arg0: dict) → pix4dvortex.dmodel.InputCameras
hash(self: pix4dvortex.dmodel.InputCameras) → int
to_dict(self: pix4dvortex.dmodel.InputCameras) → dict
property captures
opf_type = 'input_cameras'
property sensors
class pix4dvortex.dmodel.InputControlPoints(self: pix4dvortex.dmodel.InputControlPoints, *, gcps: collections.abc.Sequence[pix4dvortex.dmodel.GCP] = [], mtps: collections.abc.Sequence[pix4dvortex.dmodel.MTP] = [])

OPF input_control_points.

static from_dict(arg0: dict) → pix4dvortex.dmodel.InputControlPoints
hash(self: pix4dvortex.dmodel.InputControlPoints) → int
to_dict(self: pix4dvortex.dmodel.InputControlPoints) → dict
property gcps
property mtps
opf_type = 'input_control_points'
class pix4dvortex.dmodel.InputRigRelatives

OPF input rig relatives.

property rotation
property translation
class pix4dvortex.dmodel.IntersectionTiePoints(self: pix4dvortex.dmodel.IntersectionTiePoints, *, itps: collections.abc.Sequence[pix4dvortex.dmodel.ITP])

ITP OPF extension ITPs

static from_dict(arg0: dict) → pix4dvortex.dmodel.IntersectionTiePoints
hash(self: pix4dvortex.dmodel.IntersectionTiePoints) → int
to_dict(self: pix4dvortex.dmodel.IntersectionTiePoints) → dict
property itps
opf_type = 'ext_pix4d_input_intersection_tie_points'
class pix4dvortex.dmodel.MTP(self: pix4dvortex.dmodel.MTP, *, is_checkpoint: bool = False, id: str = '', marks: collections.abc.Sequence[pix4dvortex.dmodel.Mark] = [])

OPF MTP.

property id

The identifier or name of the MTP.

property is_checkpoint

If true, the MTP is provided by the users for the sake of quality assessment. It will not be passed to the calibration but used later to compute the re-projection error.

property marks

The set of image points that represent the projections of a 3D-point.

class pix4dvortex.dmodel.Mark(self: pix4dvortex.dmodel.Mark, *, accuracy: SupportsFloat = 0.0, position: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(2)'] = [0.0, 0.0], camera_id: SupportsInt = 0)

OPF mark.

property accuracy

A number representing the accuracy of the click. This will be used by the calibration as a weight for this mark.

property camera_id

The camera ID to reference the image.

property position

The mark position in the image.

class pix4dvortex.dmodel.MarkWithSegments(self: pix4dvortex.dmodel.MarkWithSegments, *, camera_id: SupportsInt, common_endpoint_px: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(2)'], other_endpoints_px: collections.abc.Sequence[Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(2)']], creation_method: pix4dvortex.dmodel.ITPMarkCreationMethod, accuracy: SupportsFloat | None = None)

ITP OPF extension mark with segments.

property accuracy
property camera_id
property common_endpoint_px
property creation_method
property other_endpoints_px
class pix4dvortex.dmodel.Matches(self: pix4dvortex.dmodel.Matches, *, path: os.PathLike | str | bytes)

Matches OPF extension image matches binary file wrapper.

hash(self: pix4dvortex.dmodel.Matches) → int
opf_type = 'ext_pix4d_matches'
property path
class pix4dvortex.dmodel.OmegaPhiKappa(self: pix4dvortex.dmodel.OmegaPhiKappa, *, angles_deg: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0], sigmas_deg: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0], crs: str)

Omega/phi/kappa initial orientation.

OPK angles are defined relative to the axes of a specific CRS (typically projected: X/Y/Z of that system). crs is mandatory: without it, omega/phi/kappa are three numbers with no known frame, and later steps such as ProjectedCameras cannot re-express the attitude.

Use YawPitchRoll when attitude is local-geographic rather than CRS-axis based.

class pix4dvortex.dmodel.Orientation
property angles_deg
property crs

CRS of the orientation axes. Required and used for OmegaPhiKappa; ignored for YawPitchRoll.

property sigmas_deg
property type
class pix4dvortex.dmodel.OriginalMatches(self: pix4dvortex.dmodel.OriginalMatches, *, path: os.PathLike | str | bytes)

Matches OPF extension original image matches binary file wrapper.

hash(self: pix4dvortex.dmodel.OriginalMatches) → int
opf_type = 'ext_pix4d_original_matches'
property path
class pix4dvortex.dmodel.PerspectiveInternals

OPF sensor perspective internals.

property distortion_type
property focal_length_px
property principal_point_px
property radial_distortion
property tangential_distortion
type = 'perspective'
class pix4dvortex.dmodel.ProjectedCameras

OPF projected_cameras.

static from_dict(arg0: dict) → pix4dvortex.dmodel.ProjectedCameras
hash(self: pix4dvortex.dmodel.ProjectedCameras) → int
to_dict(self: pix4dvortex.dmodel.ProjectedCameras) → dict
property captures
opf_type = 'projected_input_cameras'
property sensors
class pix4dvortex.dmodel.ProjectedCapture

OPF projected_capture.

property geolocation
property id
property orientation
class pix4dvortex.dmodel.ProjectedControlPoints(*args, **kwargs)

OPF projecred control points

Overloaded function.

  1. __init__(self: pix4dvortex.dmodel.ProjectedControlPoints, *, projected_gcps: collections.abc.Sequence[pix4dvortex.dmodel.ProjectedGCP] = []) -> None

  2. __init__(self: pix4dvortex.dmodel.ProjectedControlPoints, *, input_control_points: pix4dvortex.dmodel.InputControlPoints, scene_ref_frame: pix4dvortex.dmodel.SceneRefFrame) -> None

static from_dict(arg0: dict) → pix4dvortex.dmodel.ProjectedControlPoints
hash(self: pix4dvortex.dmodel.ProjectedControlPoints) → int
to_dict(self: pix4dvortex.dmodel.ProjectedControlPoints) → dict
opf_type = 'projected_control_points'
property projected_gcps
class pix4dvortex.dmodel.ProjectedGCP(self: pix4dvortex.dmodel.ProjectedGCP, *, id: str = '', coordinates: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0], sigmas: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0])

OPF projected GCP

property coordinates
property id
property sigmas
class pix4dvortex.dmodel.ProjectedGeolocation

OPF projected geolocation.

property position
property sigmas
class pix4dvortex.dmodel.ProjectedOrientation

OPF projected orientation.

property angles_deg
property sigmas_deg
class pix4dvortex.dmodel.ProjectedRigTranslation

OPF projected_rig_translation.

property sigmas
property values
class pix4dvortex.dmodel.ProjectedSensor

OPF projected_sensor.

property id
property rig_translation
class pix4dvortex.dmodel.RigRelativeRotation

OPF rig relative rotation.

property angles_deg
property sigmas_deg
class pix4dvortex.dmodel.RigRelativeTranslation

OPF rig relative translation.

property sigmas_m
property values_m
class pix4dvortex.dmodel.RigidTransform

OPF rigid_transform.

property rotation_deg
property scale
property translation
class pix4dvortex.dmodel.ScaleConstraint(self: pix4dvortex.dmodel.ScaleConstraint, *, id: str, id_from: str, id_to: str, distance: SupportsFloat, sigma: SupportsFloat = 0.02)

Scale constraint specifies a measured distance between two control points.

property distance

Measured distance between the two control points in the canonical CRS.

property id

ID of the scale constraint.

property id_from

ID of the first control point.

property id_to

ID of the second control point.

property sigma

Error of the measurement.

class pix4dvortex.dmodel.SceneRefFrame(self: pix4dvortex.dmodel.SceneRefFrame, *, proj_crs: pix4dvortex.dmodel.CRS = pix4dvortex.dmodel.CRS(), base_to_canonical: pix4dvortex.dmodel.BaseToCanonical = pix4dvortex.dmodel.BaseToCanonical())

OPF scene_reference_frame.

static from_dict(arg0: dict) → pix4dvortex.dmodel.SceneRefFrame
hash(self: pix4dvortex.dmodel.SceneRefFrame) → int
to_dict(self: pix4dvortex.dmodel.SceneRefFrame) → dict
property base_to_canonical

parameters used to convert the projected coordinates into the processing coordinates

property crs

Information on the projected Spatial Reference System

opf_type = 'scene_reference_frame'
class pix4dvortex.dmodel.SegmentGraph2D(self: pix4dvortex.dmodel.SegmentGraph2D, *, camera_id: SupportsInt, vertices: collections.abc.Sequence[pix4dvortex.dmodel.Vertex], edges: collections.abc.Sequence[pix4dvortex.dmodel.Edge])

2D segment graphs OPF extension 2D segment graph.

property camera_id
property edges
property vertices
class pix4dvortex.dmodel.SegmentGraphs2D(self: pix4dvortex.dmodel.SegmentGraphs2D, *, graphs: collections.abc.Sequence[pix4dvortex.dmodel.SegmentGraph2D])

2D segment graphs OPF extension item.

static from_dict(arg0: dict) → pix4dvortex.dmodel.SegmentGraphs2D
hash(self: pix4dvortex.dmodel.SegmentGraphs2D) → int
to_dict(self: pix4dvortex.dmodel.SegmentGraphs2D) → dict
property graphs
opf_type = 'ext_pix4d_2d_segment_graphs'
class pix4dvortex.dmodel.SensorElement

OPF sensor element.

property bands
property id
property image_size_px
property internals
property name
property pixel_size_um
property rig_relatives
property shutter_type
class pix4dvortex.dmodel.SphericalInternals

OPF sensor spherical internals.

property principal_point_px
type = 'spherical'
class pix4dvortex.dmodel.StaticPixelRange

OPF static pixel range.

property max
property min
class pix4dvortex.dmodel.Vertex(self: pix4dvortex.dmodel.Vertex, *, position: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(2)'], confidence: SupportsFloat)

2D segment graphs OPF extension 2D vertex.

property confidence
property position
class pix4dvortex.dmodel.YawPitchRoll(self: pix4dvortex.dmodel.YawPitchRoll, *, angles_deg: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0], sigmas_deg: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)'] = [0.0, 0.0, 0.0])

Yaw/pitch/roll initial orientation.

Yaw/pitch/roll are defined against a local geographic frame at the camera (north / local vertical, etc.). That frame is derived from the geolocation, so YawPitchRoll does not need its own CRS. The inherited crs attribute is kept for API compatibility with Orientation but is ignored.

class pix4dvortex.dmodel.WeatherCondition(self: pix4dvortex.dmodel.WeatherCondition, value: SupportsInt)

Radiometry inputs OPF extension weather condition.

CLEAR_SKY = <WeatherCondition.CLEAR_SKY: 0>

clear sky

OVERCAST = <WeatherCondition.OVERCAST: 1>

overcast sky

UNKNOWN = <WeatherCondition.UNKNOWN: 2>

unknown weather condition

class pix4dvortex.dmodel.OpticalRadiometricCorrectionType(self: pix4dvortex.dmodel.OpticalRadiometricCorrectionType, value: SupportsInt)

The type of radiometric correction done for optical sensors. Refer to User Guide’s Optical radiometry chapter for more detailed descriptions.

CAMERA = <OpticalRadiometricCorrectionType.CAMERA: 1>

Corrects camera settings and properties. Without a reflectance target, estimates at-camera radiance, when a reflectance target is used, estimates reflectance.

NONE = <OpticalRadiometricCorrectionType.NONE: 0>

No optical radiometric correction is applied (radiometry data is not available or a correction is not applicable).

SKY_SENSOR_WITHOUT_ANGLE = <OpticalRadiometricCorrectionType.SKY_SENSOR_WITHOUT_ANGLE: 2>

In addition to CAMERA corrections, uses the irradiance measured by a downwelling light sensor (DLS) to estimate reflectance, without correcting for the sensor orientation, weather condition, or sun angle.

SKY_SENSOR_WITH_ANGLE_POSE_FROM_CAMERA = <OpticalRadiometricCorrectionType.SKY_SENSOR_WITH_ANGLE_POSE_FROM_CAMERA: 3>

In addition to CAMERA corrections, uses the irradiance measured by a downwelling light sensor (DLS), the orientation of the DLS, the sun angle, and the weather condition to derive reflectance. The orientation of the DLS is derived from the camera pose and the known relative orientation between the camera and the DLS. This requires a rig between the DLS and the camera.

SKY_SENSOR_WITH_ANGLE_POSE_FROM_IMU = <OpticalRadiometricCorrectionType.SKY_SENSOR_WITH_ANGLE_POSE_FROM_IMU: 4>

In addition to CAMERA corrections, uses the irradiance measured by a downwelling light sensor (DLS), the orientation of the DLS, the sun angle, and the weather condition to derive reflectance. The orientation of the DLS is derived from an IMU inside the DLS.

SKY_SENSOR_WITH_PROVIDED_ILLUMINATION_MODEL = <OpticalRadiometricCorrectionType.SKY_SENSOR_WITH_PROVIDED_ILLUMINATION_MODEL: 5>

Uses output provided by the MicaSense DLS2 model.

class pix4dvortex.dmodel.ThermalParameter(self: pix4dvortex.dmodel.ThermalParameter, *, relative_humidity: SupportsFloat, air_temperature_K: SupportsFloat, apparent_reflected_temperature_K: SupportsFloat, emissivity: SupportsFloat)

Parameters used for computing temperature from raw thermal data.

An object of this class can be passed to make_input_cameras() to override JPEG metadata. There are no defaults. You cannot set only some values. When omitted, camera creation reads the values from FLIR or DJI radiometric JPEG (averaged; failed reads are logged, but the images remain in the processing pipeline).

Parameters:
property air_temperature_K

Outside air temperature (OAT) at the time of acquisition, in kelvin [K].

property apparent_reflected_temperature_K

Reflected apparent temperature, in kelvin [K] - an estimation of an apparent reflected temperature by measuring the apparent temperature of a reflective material with near-zero emissivity (for example aluminium foil). This is not the temperature of any of the surrounding objects, but an effective description of the interaction of all the different surrounding objects.

property emissivity

Material property which states how much radiation received from an object is emitted from that object and how much is reflected, as a fraction between 0 and 1. Typical values for common materials are listed in publicly available material tables.

property relative_humidity

Relative humidity at the time of acquisition, set as a number between 0 and 1 (0.5 means 50%).

class pix4dvortex.dmodel._SurfaceModelMesh(self: pix4dvortex.dmodel._SurfaceModelMesh)

Surface model mesh OPF extension.

class pix4dvortex.dmodel._RadiometryInputs

Radiometry inputs OPF extension.

class pix4dvortex.dmodel._RadiometrySettings

Radiometry settings OPF extension.

pix4dvortex data model

Additional pix4dvortex data types. These are often OPF type composites, legacy classes, or a mix of both. Unlike the OPF compatible classes, which are all defined in dmodel, these are defined in different modules, which also contain related processing functions and settings. For convenience, this section presents the class documentation of the main classes only. Documentation of the full public API of each class is available in the relevant Core Processing sub-sections.

class pix4dvortex.cameras.InputCameras

Composite of pix4dvortex.dmodel OPF input camera and related types.

This class wraps pix4dvortex.dmodel.InputCameras, pix4dvortex.dmodel.CameraList, and pix4dvortex.dmodel.CameraOptimizationHints, and _RadiometryData objects and provides a higher level interface with convenient data access methods.

class pix4dvortex.cameras.ProjectedCameras

Composite of pix4dvortex.dmodel OPF projected camera and related types.

This class wraps pix4dvortex.dmodel.ProjectedCameras and pix4dvortex.dmodel.SceneRefFrame, in addition to components of InputCameras, and provides a higher level interface with convenient data access methods.

class pix4dvortex.calib._CalibratedScene

Composite of pix4dvortex.dmodel OPF calibration, scene reference frame, input cameras and control points.

This class wraps pix4dvortex.dmodel.Calibration, pix4dvortex.dmodel.SceneRefFrame, pix4dvortex.dmodel.InputCameras, pix4dvortex.dmodel.InputControlPoints and pix4dvortex.dmodel._SurfaceModelMesh. and pix4dvortex.dmodel.CameraOptimizationHints, and _RadiometryData objects and provides access to these objects as well as user convenience methods.

class pix4dvortex.pcl.PointCloud

Bases: GLTFPointCloud

Composite of pix4dvortex.dmodel.GLTFPointCloud and pix4dvortex.dmodel.SceneRefFrame OPF types.

This class is a specialization of pix4dvortex.dmodel.GLTFPointCloud, with a pix4dvortex.dmodel.SceneRefFrame object and additional methods to increase usability. It is intended to model the output of a point cloud densification algorithm, with the pix4dvortex.dmodel.SceneRefFrame representing the bridge between the glTF positions - stored in the “canonical” SRS - and the “base” SRS, typically a real world “projected” SRS.

class pix4dvortex.gsplat.GaussianSplatting

Bases: GLTFGSplat

Composite of pix4dvortex.dmodel.GLTFGSplat and pix4dvortex.dmodel.SceneRefFrame OPF types.

This class is a specialization of pix4dvortex.dmodel.GLTFGSplat, with a pix4dvortex.dmodel.SceneRefFrame object and additional methods to increase usability. It is intended to model the output of a Gaussian splatting generation algorithm, with the pix4dvortex.dmodel.SceneRefFrame representing the bridge between the glTF positions - stored in the “canonical” SRS - and the “base” SRS, typically a real world “projected” SRS.

class pix4dvortex.dsm._DsmTiles
class pix4dvortex.ortho._OrthoTiles
class pix4dvortex.mesh._MeshLOD

Level of detail representation of a textured mesh

class pix4dvortex.mesh._Texture
class pix4dvortex.mesh._MeshGeom

Core Processing

Input and Calibrated Cameras

Camera-related data types, serving as input data to the processing algorithms, and utilities.

class pix4dvortex.cameras.DepthConfidenceInfo(self: pix4dvortex.cameras.DepthConfidenceInfo, *, path: os.PathLike | str | bytes, min: SupportsFloat = 0.0, threshold: SupportsFloat = 1.0, max: SupportsFloat = 2.0)
property max
property min
property path
property threshold
class pix4dvortex.cameras.DepthInfo(self: pix4dvortex.cameras.DepthInfo, *, path: os.PathLike | str | bytes, unit_to_meters: SupportsFloat | None = 1.0, confidence_info: pix4dvortex.cameras.DepthConfidenceInfo | None = None)
property confidence_info
property path
property unit_to_meters
class pix4dvortex.cameras.GeoCoordinates(self: pix4dvortex.cameras.GeoCoordinates, *, lat: SupportsFloat = 0, lon: SupportsFloat = 0.0, alt: SupportsFloat = 0.0, lat_accuracy: SupportsFloat = 0.0, lon_accuracy: SupportsFloat = 0.0, alt_accuracy: SupportsFloat = 0.0)

Deprecated: Geolocation coordinates and accuracies

Geographic coordinates and accuracies lat[°], lon[°], alt[m], σ(lat[m]), σ(lon[m]), and σ(alt[m])

Raises:

ValueError – if any coordinate or associated accuracies is out of bounds.

property alt
property alt_accuracy
property lat
property lat_accuracy
property lon
property lon_accuracy
class pix4dvortex.cameras.GeoRotation(self: pix4dvortex.cameras.GeoRotation, *, yaw: SupportsFloat = 0.0, pitch: SupportsFloat = 0.0, roll: SupportsFloat = 0.0, yaw_accuracy: SupportsFloat = 0.0, pitch_accuracy: SupportsFloat = 0.0, roll_accuracy: SupportsFloat = 0.0, unit: str = 'degrees')

Deprecated: Yaw-Pitch-Roll rotation angles and accuracies

Deprecated: Rotation angles and accuracies yaw, pitch, roll, σ(yaw), σ(pitch), and σ(roll).

Parameter unit specifies the unit of measurement of the arguments and must be one of “degrees” or “radians”.

Raises:

  • ValueError – if an invalid angular unit is chosen

  • ValueError – if any of the rotation angles or their associated accuracies is out of bounds.

property pitch
property pitch_accuracy

σ(pitch) (radians)

property roll
property roll_accuracy

σ(roll) (radians)

property yaw
property yaw_accuracy

σ(yaw) (radians)

class pix4dvortex.cameras.GeoTag(*args, **kwargs)

Geolocation and orientation in a given coordinate reference system

Overloaded function.

  1. __init__(self: pix4dvortex.cameras.GeoTag, *, geolocation: pix4dvortex.dmodel.Geolocation | None = None, orientation: pix4dvortex.dmodel.Orientation | None = None) -> None

  2. __init__(self: pix4dvortex.cameras.GeoTag, *, horizontal_srs_code: str | None = None, vertical_srs_code: str | None = None, geo_position: pix4dvortex.cameras.GeoCoordinates | None = None, geo_rotation: pix4dvortex.cameras.GeoRotation | None = None) -> None

Deprecated, use the above initialization instead.

property geo_position

Position ((lat[°], lon[°], alt[m]), (σ(lat[m]), σ(lon[m]), σ(alt[m]))). Deprecated, use ‘geolocation’ instead.

property geo_rotation

Rotation ((yaw, pitch, roll) and (σ(yaw), σ(pitch), σ(roll)) in [rad]. Deprecated, use ‘orientation’ instead.

property geolocation
property horizontal_srs_code

Get horizontal CRS component. Deprecated, retrieve the CRS from geolocation instead.

property orientation
property vertical_srs_code

Get vertical CRS component. Deprecated, retrieve the CRS from geolocation instead.

class pix4dvortex.cameras.InputCameras(*args, **kwargs)

Composite of pix4dvortex.dmodel OPF input camera and related types.

This class wraps pix4dvortex.dmodel.InputCameras, pix4dvortex.dmodel.CameraList, and pix4dvortex.dmodel.CameraOptimizationHints, and _RadiometryData objects and provides a higher level interface with convenient data access methods.

Overloaded function.

  1. __init__(self: pix4dvortex.cameras.InputCameras) -> None

  2. __init__(self: pix4dvortex.cameras.InputCameras, *, input_cameras: pix4dvortex.dmodel.InputCameras, camera_list: pix4dvortex.dmodel.CameraList, optimization_hints: pix4dvortex.dmodel.CameraOptimizationHints | None = None, radiometry_data: pix4dvortex.cameras._RadiometryData | None = None) -> None

change_rig_reference_sensor(self: pix4dvortex.cameras.InputCameras, *, new_reference_sensor_id: SupportsInt) → dict[int, pix4dvortex.cameras.RigGeometry]

Change the reference sensor of the rig and update the rig relatives in the input cameras.

get_depth_info(self: pix4dvortex.cameras.InputCameras, *, camera_id: SupportsInt) → pix4dvortex.cameras.DepthInfo | None

Depth information corresponding to camera with given ID.

Raises:

IndexError – if camera_id not valid.

get_image_path(self: pix4dvortex.cameras.InputCameras, *, camera_id: SupportsInt) → pathlib.Path

Path of image file with given camera ID.

Raises:

IndexError – if camera_id not valid.

optimization_hints(self: pix4dvortex.cameras.InputCameras) → pix4dvortex.dmodel.CameraOptimizationHints
radiometry_data(*args, **kwargs)

Overloaded function.

  1. radiometry_data(self: pix4dvortex.cameras.InputCameras) -> pix4dvortex.cameras._RadiometryData | None

  2. radiometry_data(self: pix4dvortex.cameras.InputCameras, arg0: pix4dvortex.cameras._RadiometryData) -> None

rig_geometries(self: pix4dvortex.cameras.InputCameras) → dict[int, pix4dvortex.cameras.RigGeometry]

Returns the geometry of the rigs from the input cameras.

class pix4dvortex.cameras.ProjectedCameras(*args, **kwargs)

Composite of pix4dvortex.dmodel OPF projected camera and related types.

This class wraps pix4dvortex.dmodel.ProjectedCameras and pix4dvortex.dmodel.SceneRefFrame, in addition to components of InputCameras, and provides a higher level interface with convenient data access methods.

Overloaded function.

  1. __init__(self: pix4dvortex.cameras.ProjectedCameras, *, input_cameras: pix4dvortex.cameras.InputCameras, proj_srs: pix4dvortex.coordsys.SpatialReference | None = None, proj_srs_geoid_height: typing.SupportsFloat | None = None) -> None

Create a ProjectedCameras instance.

Parameters:

  • input_cameras – A container of input camera objects.

  • proj_srs – (optional) Projected coordinate system to be used for camera calibration. Must be isometric. If not specified, a UTM corresponding to the geographic coordinate system of the first image with geolocation is used.

  • proj_srs_geoid_height – (optional, only accepted for compound proj_srs without a geoid model). The geoid height (aka geoid undulation approximation) to use when the coordinates of the images are using an SRS that require conversion to the proj SRS (proj_srs).

Returns:

A ProjectedCameras object. Its coordinate system is either proj_srs if it is specified or UTM otherwise.

Raises:

  • RuntimeError – if any of the images is not geo-located.

  • RuntimeError – if proj_srs is not set and the projected SRS derived from images is not isometric.

  • RuntimeError – if proj_srs is set and is not both projected and isometric.

  1. __init__(self: pix4dvortex.cameras.ProjectedCameras, *, projected_cameras: pix4dvortex.dmodel.ProjectedCameras, input_cameras: pix4dvortex.dmodel.InputCameras, camera_list: pix4dvortex.dmodel.CameraList, scene_ref_frame: pix4dvortex.dmodel.SceneRefFrame, optimization_hints: pix4dvortex.dmodel.CameraOptimizationHints | None = None, radiometry_data: pix4dvortex.cameras._RadiometryData | None = None) -> None

Create a ProjectedCameras from OPF objects.

get_depth_info(self: pix4dvortex.cameras.ProjectedCameras, *, camera_id: SupportsInt) → pix4dvortex.cameras.DepthInfo | None

Depth information corresponding to camera with given ID.

Raises:

IndexError – if camera_id not valid.

get_image_path(self: pix4dvortex.cameras.ProjectedCameras, *, camera_id: SupportsInt) → pathlib.Path

Path of image file with given camera ID.

Raises:

IndexError – if camera_id not valid.

optimization_hints(self: pix4dvortex.cameras.ProjectedCameras) → pix4dvortex.dmodel.CameraOptimizationHints
radiometry_data(self: pix4dvortex.cameras.ProjectedCameras) → pix4dvortex.cameras._RadiometryData | None
property captures

A list of calibration Capture objects.

property proj_srs

The projected spatial reference system.

property proj_srs_geoid_height
property scene_ref_frame

Information on the internal processing spatial reference system

class pix4dvortex.cameras.RigGeometry

Represents the geometry of a rig, including the reference sensor identifier and the relative positions and rotations of all sensors within the rig.

property reference_sensor_id
property rig_relatives
class pix4dvortex.cameras.RigRelativePositionAndRotation

Represents the relative position and rotation of a sensor within a rig with respect to the reference sensor. The rotation angles (a, b, c) are in radians and define a rotation matrix R_x(a)R_y(b)R_z(c) that transforms from the image coordinate system of the secondary camera to the reference one. Each image coordinate system is defined as x pointing right, y pointing down and z pointing in the direction the camera is looking. The position is always measured in meter.

property position
property rotation
class pix4dvortex.cameras.Settings(self: pix4dvortex.cameras.Settings, *, uid_gen: pix4dvortex.cameras.UIDGen = UIDGen.BLAKE2B_8_FILE_HASH, camera_db_path: os.PathLike | str | bytes | None = None, radiometry: pix4dvortex.cameras.Settings.Radiometry | None = None)

Configuration settings for InputCameras creation.

Parameters:

  • uid_gen – (optional) OPF camera UID generator.

  • radiometry – (optional) experimental radiometric processing settings.

class Radiometry(self: pix4dvortex.cameras.Settings.Radiometry, *, weather_condition: pix4dvortex.dmodel.WeatherCondition = WeatherCondition.CLEAR_SKY, _preferred_correction_type: pix4dvortex.dmodel.OpticalRadiometricCorrectionType | None = None, target_search_count: SupportsInt = 3)
property target_search_count

Number of captures at the beginning and end to check for reflectance targets.

property weather_condition

Weather conditions under which the data were captured.

to_dict(self: pix4dvortex.cameras.Settings) → dict
property camera_db_path

User defined alternative camera DB path.

property radiometry

Radiometry settings

property uid_gen

OPF camera UID generator

class pix4dvortex.cameras.UIDGen(self: pix4dvortex.cameras.UIDGen, value: SupportsInt)
BLAKE2B_8_FILE_HASH = <UIDGen.BLAKE2B_8_FILE_HASH: 0>
IMG_CONTENT_HASH = <UIDGen.IMG_CONTENT_HASH: 1>
pix4dvortex.cameras.make_input_cameras(*, image_info: collections.abc.Sequence[os.PathLike | str | bytes], depth_info: collections.abc.Mapping[os.PathLike | str | bytes, pix4dvortex.cameras.DepthInfo] | None = None, camera_db_path: os.PathLike | str | bytes | None = None, external_geotags: collections.abc.Mapping[os.PathLike | str | bytes, pix4dvortex.cameras.GeoTag] = {}, settings: pix4dvortex.cameras.Settings = pix4dvortex.cameras.Settings(), thermal_parameter: pix4dvortex.dmodel.ThermalParameter | None = None, logger: collections.abc.Callable[[SupportsInt, str], None] = None, _stats: collections.abc.Callable[[dict], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.cameras.InputCameras

Create an InputCameras instance.

The optional external_geotags argument is used to 1) set geotags for not geolocated images. Geotags must contain coordinates and SRS codes, and optionally also rotation data, failing that, a ValueError: is raised. 2) update existing geotags. Geotags can contain any combination of SRS code, coordinates and rotation data.

Parameters:

  • image_info – List of image file paths to create cameras from.

  • depth_info – (optional): Mapping of image file path to corresponding depth and depth confidence.

  • camera_db_path – (optional, deprecated) path of camera database. Embedded one is used if not set. Use settings.camera_db_path instead.

  • external_geotags – (optional) mapping of image paths to geotags.

  • settings – (optional) configuration settings.

  • thermal_parameter – (optional) ThermalParameter used to compute temperature from a radiometric JPEG. Pass all four fields, or omit the argument. There are no defaults. When omitted, values are read from FLIR or DJI radiometric JPEG metadata (averaged; camera estimates). Failed reads are logged; images are not removed from the processing pipeline.

  • logger – (optional) logging callable object.

  • _stats – (optional) call-back accessing image metadata and stats.

  • progress_callback – (optional) Callback function to report progress (step, percentage). Reports a single step named Creating input cameras from 0 to 100.

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:

  • ValueError – if any of the images causes a camera creation error

  • ValueError – if any element of depth_info does not map to an image in image_info.

  • RuntimeError – if any element of image_info or depth_info does not map to an existing file.

  • ValueError – if the new geolocation misses coordinates.

  • ValueError – if external_geotags does not reference an existing file.

  • RuntimeError – if any of the mapped geotags does not map to an image in image_info.

  • ValueError – if two image files are bit-wise identical.

pix4dvortex.cameras.version() → str
class pix4dvortex.cameras._RadiometryData(self: pix4dvortex.cameras._RadiometryData, *, _radiometry_inputs: pix4dvortex.dmodel._RadiometryInputs | None = None, _radiometry_settings: pix4dvortex.dmodel._RadiometrySettings | None = None)

Composite of pix4dvortex.dmodel._RadiometryInputs and pix4dvortex.dmodel._RadiometrySettings OPF extension types.

Contains radiometric input from reflectance targets, radiometric corrections for each sensor, as well as the orthomosaic settings used to generate the radiometric input data. Objects of this class are used internally in the ortho and indexmap modules when generating multispectral orthomosaics and reflectance maps.

Camera Calibration

Module for calibration utilities.

class pix4dvortex.calib.ReoptSettings(self: pix4dvortex.calib.ReoptSettings, *, calibration_int_param_opt: pix4dvortex.calib.Settings.OptimIntType = OptimIntType.All, calibration_int_param_strategy: pix4dvortex.calib.Settings.OptimIntStrategy = OptimIntStrategy.Default, calibration_ext_param_opt: pix4dvortex.calib.Settings.OptimExtType = OptimExtType.All, use_optimized_internals: bool = True, rematch_additional_settings: pix4dvortex.calib.ReoptSettings.RematchAdditional | None = None, _lever_arm_opt: pix4dvortex.calib.Settings._LeverArmType = _LeverArmType.NoOffset)
class RematchAdditional(self: pix4dvortex.calib.ReoptSettings.RematchAdditional, *, image_pair_settings: pix4dvortex.calib.Settings.ImagePairSettings = pix4dvortex.calib.Settings.ImagePairSettings(), is_oblique_scene: bool = False)
to_dict(self: pix4dvortex.calib.ReoptSettings.RematchAdditional) → dict
property image_pair_settings

Settings for image pair generation. See ImagePairSettings.

property is_oblique_scene
to_dict(self: pix4dvortex.calib.ReoptSettings) → dict
property calibration_ext_param_opt

Type of optimization for external camera parameters. See OptimExtType.

property calibration_int_param_opt

Type of optimization for internal camera parameters. See OptimIntType.

property calibration_int_param_strategy

Strategy defining at which steps of the calibration process the internal camera parameters are optimized. See OptimIntStrategy.

property rematch_additional_settings
property use_optimized_internals

Specifies whether to use the optimized internals from the calibrated scene or the internals from the initial cameras. Use False if you have updated the internals in the initial cameras and want to use their value instead of the optimization results.

pix4dvortex.calib.calibrate(*, cameras: pix4dvortex.cameras.ProjectedCameras, settings: pix4dvortex.calib.Settings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), control_points: pix4dvortex.dmodel.InputControlPoints | None = None, constraints: pix4dvortex.dmodel.Constraints | None = None, _keypoint_metrics_handler: collections.abc.Callable[[pix4dvortex.calib.analytics._KeypointMetrics], None] = None, _metrics_handler: collections.abc.Callable[[str, str], None] | None = None, logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.calib._CalibratedScene

Calibrate cameras.

Parameters:

  • cameras – Projected cameras container.

  • settings – The calibration settings, see Settings.

  • resources – [Optional] HW resource configuration parameters.

  • control_points – [Optional] The input control points, see InputControlPoints. If settings.use_gcp_srs is False, the SRS of GCPs must be the same as the system used in cameras, otherwise all GCPs must use the same Cartesian and isometric system (e.g. projected, 3D engineering or compound of projected and vertical).

  • constraints – [Optional] Constraints to apply during calibration, see Constraints.

  • _keypoint_metrics_handler – [Optional] An optional callable to handle a object generated during calibration. Its single argument provides a _KeypointMetrics.

  • logger – [Optional] Logging callback.

  • progress_callback – [Optional] Callback function to report progress (step, percentage). Reports a single step named Calibrating from 0 to 100.

  • stop_function – [Optional] Callback function to request stopping; return True to stop processing.

Raises:
Returns:

A calibrated scene, see _CalibratedScene.

pix4dvortex.calib.reoptimize(*, cameras: pix4dvortex.cameras.ProjectedCameras, scene: pix4dvortex.calib._CalibratedScene, settings: pix4dvortex.calib.ReoptSettings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), control_points: pix4dvortex.dmodel.InputControlPoints | None = None, constraints: pix4dvortex.dmodel.Constraints | None = None, _metrics_handler: collections.abc.Callable[[str, str], None] | None = None, logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.calib._CalibratedScene

Reoptimize a scene.

Parameters:

  • cameras – Projected cameras container.

  • scene – The calibrated scene.

  • settings – The reoptimize settings, see ReoptSettings.

  • resources – [Optional] HW resource configuration parameters.

  • control_points – [Optional] The input control points, see InputControlPoints.

  • constraints – [Optional] Constraints to apply during calibration, see Constraints.

  • logger – [Optional] Logging callback.

  • progress_callback – [Optional] Callback function to report progress (step, percentage).

  • stop_function – [Optional] Callback function to request stopping; return True to stop processing.

Raises:
Returns:

A calibrated scene, see _CalibratedScene.

pix4dvortex.calib.version() → str
class pix4dvortex.calib.Settings(self: pix4dvortex.calib.Settings, *, keypt_number: SupportsInt | None = None, image_scale: SupportsFloat = 1.0, matching_algorithm: pix4dvortex.calib.Settings.MatchingAlgorithm = MatchingAlgorithm.Standard, image_pair_settings: pix4dvortex.calib.Settings.ImagePairSettings = pix4dvortex.calib.Settings.ImagePairSettings(), use_rig_matching: bool = False, min_matches: SupportsInt = 20, min_image_distance: SupportsFloat = 0.0, pipeline: pix4dvortex.calib.Settings.CalibrationType = CalibrationType.Standard, calibration_int_param_opt: pix4dvortex.calib.Settings.OptimIntType = OptimIntType.All, calibration_int_param_strategy: pix4dvortex.calib.Settings.OptimIntStrategy = OptimIntStrategy.Default, calibration_ext_param_opt: pix4dvortex.calib.Settings.OptimExtType = OptimExtType.All, prior_position_confidence: pix4dvortex.calib.Settings.PriorPositionConfidenceType = PriorPositionConfidenceType.Low, oblique: bool = True, rematch: pix4dvortex.calib.Settings.ReMatchingAlgorithm | bool | None = ReMatchingAlgorithm.NoRematch, pipeline_strategy: pix4dvortex.calib.Settings.PipelineStrategy = PipelineStrategy.Standard, use_gcp_srs: bool = False, use_itps: bool = False, save_intermediate_results: bool = False, _lever_arm_opt: pix4dvortex.calib.Settings._LeverArmType = _LeverArmType.NoOffset, _rig_relative_opt: pix4dvortex.calib.Settings._ApiRigRelativesOptimType = _ApiRigRelativesOptimType.RotationUsingSubsetOfCaptures, _use_sensor_characteristics: bool = True)
class ImageDistance(self: pix4dvortex.calib.Settings.ImageDistance, arg0: SupportsFloat)

Images distance. The unit of measure is the one of the processing SRS (usually meter of feet). See SceneRefFrame.

to_dict(self: pix4dvortex.calib.Settings.ImageDistance) → dict
property value
class ImageDistanceToMedian(self: pix4dvortex.calib.Settings.ImageDistanceToMedian, arg0: SupportsFloat)

Images distance relative to median distance of consecutive images

to_dict(self: pix4dvortex.calib.Settings.ImageDistanceToMedian) → dict
property value
class OptimIntStrategy(self: pix4dvortex.calib.Settings.OptimIntStrategy, value: SupportsInt)

Strategy defining at which steps of the calibration process the internal camera parameters are optimized (complements OptimIntType, which controls which parameters are optimized).

Default = <OptimIntStrategy.Default: 0>

(default) Optimizes camera internal parameters in all relevant calibration bundles, as requested by OptimIntType. Use when internals should continue to be refined throughout calibration, including later and GCP-related bundles - normal case for most aerial and terrestrial projects.

LockAfterSceneBuildup = <OptimIntStrategy.LockAfterSceneBuildup: 1>

Optimizes camera internal parameters during scene buildup (early calibration phase), then keeps them constant in subsequent bundles including the final bundle with control points and constraints (stops optimizing internals whether the project has GCPs or not). Recommended for difficult aerial (non-flat) and terrestrial projects when calibrating with MTPs/GCPs and flaky GPS/partial RTK. Currently preset in CATCH.

LockAfterSceneBuildupWithoutGcps = <OptimIntStrategy.LockAfterSceneBuildupWithoutGcps: 2>

Optimizes camera internal parameters during scene buildup as LockAfterSceneBuildup does, then locks internals after scene buildup only if there are no GCPs. If the project does include GCPs, it continues to optimize internals in GCP-related bundles, but still locks rematch. Recommended typically for flat or low-texture scenes (without GCPs) to help prevent scene bending. Currently preset in FLAT.

class PipelineStrategy(self: pix4dvortex.calib.Settings.PipelineStrategy, value: SupportsInt)
Auto = <PipelineStrategy.Auto: 2>

A pipeline strategy is selected automatically.

Robust = <PipelineStrategy.Robust: 1>

More robust to inaccurate geotags and/or hard to match images. It may result in slower processing.

Standard = <PipelineStrategy.Standard: 0>

Default behavior.

class PriorPositionConfidenceType(self: pix4dvortex.calib.Settings.PriorPositionConfidenceType, value: SupportsInt)

Confidence that the input prior positions for the cameras contain no outlier.

High = <PriorPositionConfidenceType.High: 1>

Low number of outliers expected.

Low = <PriorPositionConfidenceType.Low: 0>

(default) Outlier or inconsistent positions MAY be present in the input.

class ReMatchingAlgorithm(self: pix4dvortex.calib.Settings.ReMatchingAlgorithm, value: SupportsInt)
Auto = <ReMatchingAlgorithm.Auto: 3>

A rematching algorithm is selected automatically.

NoRematch = <ReMatchingAlgorithm.NoRematch: 0>

Do not run any rematching.

Robust = <ReMatchingAlgorithm.Robust: 2>

A more robust rematching strategy for difficult projects.

Standard = <ReMatchingAlgorithm.Standard: 1>

Adequate for most capture cases.

to_dict(self: pix4dvortex.calib.Settings) → dict
property calibration_ext_param_opt

Type of optimization for external camera parameters. See OptimExtType.

property calibration_int_param_opt

Type of optimization for internal camera parameters. See OptimIntType.

property calibration_int_param_strategy

Strategy defining at which steps of the calibration pipeline the internal camera parameters are optimized. See OptimIntStrategy.

property image_pair_settings

Settings for image pair generation. See ImagePairSettings.

property image_scale

Image scale at which features are computed. The scale is a ratio to the initial size of the image. Recommended values:

  • 0.5 for RGB images from 40Mpx and above

  • 0.5-1.0 for RGB images from 12 to 40Mpx

  • 1.0-2.0 for images with lower resolutions (multispectral, mobile captures, etc.)

property keypt_number

Target number of keypoints per image for matching. If set to None, the value will be automatically determined.

property matching_algorithm

Matching algorithm. See MatchingAlgorithm.

property min_image_distance

Minimum distance (in xy-plane) for matching or for homography estimation. In most of the cases it doesn’t make sense to eliminate closest images from matching, therefore the recommended value is 0.0.

property min_matches

Sets a threshold for the minimum matches per an image pair to be considered in calibration. The pair is fully discarded if the number of the matches in the pair is less than this threshold. Recommended value is 20.

property oblique

Type of flight plan:

  • True for oblique or free flight (default)

  • False for nadir flight

property pipeline

Type of calibration pipeline. See CalibrationType and user guide for more information.

property pipeline_strategy

The calibration pipeline strategy, it applies only to CalibrationType.TrustedLocationOrientation. See PipelineStrategy.

property prior_position_confidence

Confidence that the input prior positions for the cameras contain no outlier.

property rematch

The rematching algorithm.

Rematching adds more matches after the first part of the initial processing.

This usually improves the quality of the results at the cost of increasing the processing time. See ReMatchingAlgorithm.

(Deprecated) Set True to enable rematching.

property save_intermediate_results

Save features and matches computed during calibration as binary files. This allows to speed up any subsequent calls to reoptimize. Note: the binary files may have a significant size (order of magnitude of the size of input images).

property use_gcp_srs

Use SRS defined in GCPs rather than projected cameras for deriving the scene reference frame definition.

property use_itps

Generate tie points out of structural line intersections to help calibrate the scene.

property use_rig_matching

Combine matches of all cameras in a rig instance when matching. Only relevant for rig multispectral captures and pipeline = LowTexturePlanar together with matching_algorithm = GeometricallyVerified.

class pix4dvortex.calib.Settings.TEMPLATES

Pre-defined settings for commonly used data capture types.

LARGE

Optimized for use with aerial non-multispectral image captures of large scenes.

FLAT

Optimized for aerial nadir data sets of flat, possibly low-texture, scenes. Well suited for multispectral cameras (rigs).

MAPS_3D

Optimized for small (less than 500 images) aerial nadir or oblique data sets with high image overlap acquired in a grid flight plan.

MODELS_3D

Optimized for aerial oblique or terrestrial data sets with high image overlap.

CATCH

Specifically designed for data sets captured by PIX4Dcatch.

RTK

Optimized for RTK aerial non-multispectral image captures of large scenes.

class pix4dvortex.calib._CalibratedScene(self: pix4dvortex.calib._CalibratedScene, *, calibration: pix4dvortex.dmodel.Calibration = pix4dvortex.dmodel.Calibration(), scene_ref_frame: pix4dvortex.dmodel.SceneRefFrame = pix4dvortex.dmodel.SceneRefFrame(), input_cameras: pix4dvortex.dmodel.InputCameras = pix4dvortex.dmodel.InputCameras(), ground_mesh: pix4dvortex.dmodel._SurfaceModelMesh | None = None, input_control_points: pix4dvortex.dmodel.InputControlPoints | None = None, segment_graphs_2d: pix4dvortex.dmodel.SegmentGraphs2D | None = None)

Composite of pix4dvortex.dmodel OPF calibration, scene reference frame, input cameras and control points.

This class wraps pix4dvortex.dmodel.Calibration, pix4dvortex.dmodel.SceneRefFrame, pix4dvortex.dmodel.InputCameras, pix4dvortex.dmodel.InputControlPoints and pix4dvortex.dmodel._SurfaceModelMesh. and pix4dvortex.dmodel.CameraOptimizationHints, and _RadiometryData objects and provides access to these objects as well as user convenience methods.

Construct from a set of OPF objects

class pix4dvortex.calib.Settings.CalibrationType(self: pix4dvortex.calib.Settings.CalibrationType, value: SupportsInt)

Type of calibration pipeline. See user guide for more information.

LowTexturePlanar = <CalibrationType.LowTexturePlanar: 2>

Legacy calibration pipeline (‘Alternate’ in Mapper) designed for aerial nadir images with accurate geolocations and homogeneous or repetitive content of flat-like scenes and rig cameras. It ignores the image orientations.

Scalable = <CalibrationType.Scalable: 1>

All-purpose calibration pipeline including support for large-scale, corridor and uncorrected GPS accuracy-referenced captures. It does not support multispectral rigs.

TrustedLocationOrientation = <CalibrationType.TrustedLocationOrientation: 3>

This calibration pipeline is designed for projects with accurate relative locations and inertial measurement unit (IMU) data (image orientations). All images must include highly accurate positions and orientation information, for example, from RTK/PPK.

class pix4dvortex.calib.Settings.ImagePairSettings(self: pix4dvortex.calib.Settings.ImagePairSettings, *, match_all: bool = False, match_use_triangulation: bool = True, _match_use_orientation: bool = False, _cnv_to_meter_factor: SupportsFloat = 1.0, match_mtp_max_image_pair: SupportsInt = 50, match_inter_sensor_images: SupportsInt = 0, match_similarity_images: SupportsInt = 2, match_time_images: SupportsInt = 2, min_rematch_overlap: SupportsFloat = 0.30000001192092896, match_distance_images: pix4dvortex.calib.Settings.ImageDistance | pix4dvortex.calib.Settings.ImageDistanceToMedian = pix4dvortex.calib.Settings.ImageDistanceToMedian(), _match_loop: pix4dvortex.calib.Settings._MatchLoopSettings = pix4dvortex.calib.Settings._MatchLoopSettings())
to_dict(self: pix4dvortex.calib.Settings.ImagePairSettings) → dict
property match_all

If True the algorithm will try to find matches in every image pair combination. This will effectively ignore others ImagePairSettings parameters. It is not recommended due to a severe impact on the processing time. Recommended value is False.

property match_distance_images

Match images with distance smaller than this. This distance must be expressed using either the ImageDistance type or the ImageDistanceToMedian type. The distance is 3D if all components are available and 2D (XY plane) otherwise.

Setting a value (greater than zero) is useful for oblique or terrestrial projects.

property match_inter_sensor_images

This setting has been introduced for matching images from multiple camera sensors flown at the same time, when the sensors are not part of a rig or the sensors are not sufficiently synchronized. It purpose is similar to the match_time_images, but for cameras with multiple sensors. Using zero disables this strategy.

property match_mtp_max_image_pair

Strategy generating image pairs matches, using images connected by control point marks. This strategy limits to number of generated image pair, up to match_mtp_max_image_pair per control point. Using zero disables this strategy.

property match_similarity_images

Matching image pairs based on an internal content similarity algorithm. The number defines the maximum number of image pairs that can be matched based on similarity. Zero value disables this matching image pair strategy.

property match_time_images

Matching images consecutively considering their timestamp of capture. The number defines how many consecutive images (using timestamp ordering) are considered for pair matching. Zero value disables this matching image pair strategy. Typical values: 2 - 4

property match_use_triangulation

Strategy using the geolocation of the images to guess how likely image pairs are to match. Recommended value is True.

property min_rematch_overlap

Minimum relative overlap required for an image pair to be considered in the rematch process. This settings is only relevant when rematch is True. Typical value: 0.3

class pix4dvortex.calib.Settings.MatchingAlgorithm(self: pix4dvortex.calib.Settings.MatchingAlgorithm, value: SupportsInt)
Auto = <MatchingAlgorithm.Auto: 2>

A matching algorithm is selected automatically.

GeometricallyVerified = <MatchingAlgorithm.GeometricallyVerified: 1>

A slower, but more robust matching strategy. If selected, geometrically inconsistent matches are discarded. The option is useful when many similar features are present throughout the project: rows of plants in a farming field, window corners on a building’s facade, etc.

Standard = <MatchingAlgorithm.Standard: 0>

Default and adequate for most capture cases.

class pix4dvortex.calib.Settings.OptimExtType(self: pix4dvortex.calib.Settings.OptimExtType, value: SupportsInt)

Type of optimization for external camera parameters. External camera parameters are position and orientation, and the linear rolling shutter in case the camera model follows the linear rolling shutter model.

All = <OptimExtType.All: 2>

(default) Optimizes the rotation and position, as well as the linear rolling shutter in case the camera model follows the linear rolling shutter model.

Motion = <OptimExtType.Motion: 1>

Optimizes rotation and orientation, but not the rolling shutter.

NoOptim = <OptimExtType.NoOptim: 0>

Does not optimize any of the external camera parameters. It should be used only when the camera orientation and position are known to be very accurate.

class pix4dvortex.calib.Settings.OptimIntType(self: pix4dvortex.calib.Settings.OptimIntType, value: SupportsInt)

Type of optimization for internal camera parameters. Internal camera parameters are camera sensor parameters (f.i. focal length, distortion, etc).

All = <OptimIntType.All: 2>

(default) Optimizes all the internal camera parameters (including the rolling shutter if applicable). It is recommended to use this method when processing images taken with small UAVs, whose cameras are more sensitive to temperature variations and vibrations.

AllPrior = <OptimIntType.AllPrior: 3>

Optimizes all the internal camera parameters (including the rolling shutter if applicable), but forces the optimal internal parameters to be close to the initial values. This settings may be useful for difficult to calibrate projects, where the initial camera parameters are known to be reliable.

Leading = <OptimIntType.Leading: 1>

Optimizes the most important internal camera parameters only. This option is recommended to process cameras with a slow rolling shutter speed.

NoOptim = <OptimIntType.NoOptim: 0>

Does not optimize any of the internal camera parameters. It may be beneficial for large cameras, if already calibrated, and if these calibration parameters are used for processing.

Point Cloud Densification

Module for densification utilities.

pix4dvortex.dense.densification(*, scene: pix4dvortex.calib._CalibratedScene, input_cameras: pix4dvortex.cameras.InputCameras, _metrics_handler: collections.abc.Callable[[str], None] | None = None, mask_map: collections.abc.Mapping[SupportsInt, os.PathLike | str | bytes] | None = None, roi: pix4dvortex.geom.Roi2D | None = None, settings: pix4dvortex.dense.Settings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → tuple[pix4dvortex.pcl.PointCloud, dict[int, pix4dvortex.cameras.DepthInfo] | None]

Generate densified point cloud.

Parameters:

  • scene – Calibrated scene.

  • input_cameras – input cameras container. Needed to obtain image path information.

  • _metrics_handler –

    An optional metric callback. Its single argument provides a JSON string of computed densification metrics. The underlying JSON contains below fields:

    * “pre_track_count_distrib”

    a list of track-count indexed by camera-count computed before excluding images from densification

    * “post_track_count_distrib”

    a list of track-count indexed by camera-count computed after excluding images from densification

  • mask_map – Mapping of an image file hash to the path of the mask corresponding to this image. A mask is a single-channel black-and-white image. White areas are masked. Points that project onto masked areas will not be considered for densification.

  • roi – A polygon or muti-polygon defining a 2D region of interest (XY). Points within the (multi-)polygon are considered to belong to the ROI.

  • settings – Configuration parameters, see Settings.

  • resources – HW resource configuration parameters.

  • logger – Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
Returns:

Tuple of a PointCloud and synthetic depth maps. The synthetic depth maps is None if settings.compute_depth_maps is False. The format of the depth maps is a dictionary mapping each camera ID to the corresponding DepthInfo.

pix4dvortex.dense.version() → str
pix4dvortex.dense.MAX_GPU_MEM = 8000000000

The maximum amount of GPU memory recommended (in bytes) to allocate for densification.

pix4dvortex.dense.MAX_RAM = 32000000000

The maximum amount of RAM recommended (in bytes) to allocate for densification.

class pix4dvortex.dense.Settings(self: pix4dvortex.dense.Settings, *, image_scale: SupportsInt = 1, point_density: SupportsInt = 2, min_no_match: SupportsInt = 3, window_size: SupportsInt = 7, multi_scale: bool = True, limit_depth: bool = False, regularized_multiscale: bool = False, min_image_size: SupportsInt = 512, depth_limit_percentile: SupportsFloat = 0.949999988079071, uniformity_threshold: SupportsFloat = 0.03125, compute_depth_maps: bool = False, camera_filter: pix4dvortex.dense.Settings.CameraFilter = CameraFilter.RigReferenceCameras, _partition_input_scene: bool = True, _patch_filtering: bool = True)
class CameraFilter(self: pix4dvortex.dense.Settings.CameraFilter, value: SupportsInt)
HighestMegapixel = <CameraFilter.HighestMegapixel: 2>

In case of cameras with different resolution, only use those that have the highest number of megapixels. For example, for a combination of a thermal and an RGB cameras, this can be used to select only the RGB.

NoFilter = <CameraFilter.NoFilter: 0>
RigReferenceCameras = <CameraFilter.RigReferenceCameras: 1>

Only use rig reference cameras and no secondary rig cameras.

to_dict(self: pix4dvortex.dense.Settings) → dict
property camera_filter

Allow to filter the cameras passed to the densification.

property compute_depth_maps

If True synthetic depth maps (ie. artificial depth information) are computed during densification. Setting this option will increase the densification processing time by approximately 30%. Synthetic depth maps can be used later as a constraint in the mesh generation step. This option should be turned on only for specific cases when users try to generate 3D meshes of thin structures, for instance high tension towers or power lines.

property depth_limit_percentile

If limit_depth is True, this setting is used to compute the depth limit. Considering the distribution of the tracks depths with respect to their visible cameras, the depth limit will be set to the corresponding percentile of this distribution. The default value is recommended.

property image_scale

The image scale defines the downsampling factor of the highest resolution image that will be used for the processing. The downsampling factor is defined as (1/2)**image_scale. Increasing image_scale value results in using less time and resources, and generate less 3D points. When processing vegetation, increasing image_scale can generate more 3D points. Possible values:

  1. Use the original image size. Does not significantly improve results over half size images.

  2. Use half size images. This is the recommended value.

  3. Use quarter size images.

  4. Use eighth size images.

property limit_depth

If set to True, limit the depth at which points are reconstructed, avoiding reconstructing background objects - useful for 3D models of objects. The depth limit is estimated from input cameras, points and the depth_limit_percentile parameter. This may reduce the reconstruction of outlying points. It is recommended to enable this option for oblique projects.

property min_image_size

Minimal image size used when densifying with multi_scale enabled. This determines the largest scale at which images will be used. The default value is recommended.

property min_no_match

Minimum number of valid re-projections that a 3D point must have on images to be kept in the point cloud (minimum number of matches necessary to reconstruct a point). Higher values can reduce noise, but also decrease the number of computed 3D points. Possible values:

  1. Each 3D point has to be correctly re-projected in at least 2 images. This option is recommended for projects with small overlap, but it usually produces a point cloud with more noise and artifacts.

  2. Each 3D point has to be correctly re-projected in at least 3 images (default value).

  3. Each 3D point has to be correctly re-projected in at least 4 images.

  4. Each 3D point has to be correctly re-projected in at least 5 images. This option reduces the noise and improves the quality of the point cloud, but it might compute less 3D points in the final point cloud. It is recommended for oblique imagery projects that have a high overlap.

  5. Each 3D point has to be correctly re-projected in at least 6 images. This option reduces the noise and improves the quality of the point cloud, but it might compute less 3D points in the final point cloud. It is recommended for oblique imagery projects that have a very high overlap.

property multi_scale

When this option is set to True (default value), the algorithm uses the lower resolutions of the same images in addition to the resolution chosen by image_scale parameter. Using this option results in improved completeness at the expense of increased noise in some cases. In particular the reconstruction of uniform areas such as roads is improved. This option is generally useful for computing additional 3D points in vegetation areas keeping details in areas without vegetation.

property point_density

The point density has an impact on the number of generated 3D points. It defines the minimal distance on the image plane that two points reconstructed from the same camera can have, in pixels. The distance applies to the image resolution rescaled with image_scale. The number of generated points scales as the inverse power of two of this parameter. Possible values:

  1. High density. A 3D point is computed for every image_scale pixel. The result will be an oversampled point cloud. Processing at high density typically requires more time and resources than processing at optimal density. Usually, this option does not significantly improve the results.

  2. Optimal density. A 3D point is computed for every 4/image_scale pixel. For example, if the image_scale is set to half image size, one 3D point is computed every 4/(0.5) == 8 pixels of the original image. This is the recommended value.

  1. Low density. A 3D point is computed for every 16/image_scale pixel. For example, if the image_scale is set to half image size, one 3D point is computed every 16/(0.5) = 32 pixels of the original image. The final point cloud is computed faster and uses less resources than optimal density.

property regularized_multiscale

Use patches at lower resolution only in case of uniformity failures. This setting is recommended for oblique project with enabled multiscale to limit outliers due to sky & water surfaces or other uniform backgrounds (generally with poor or no depth perception). The option has no effect if multi_scale is disabled.

property uniformity_threshold

This sets a threshold on the minimum texture content necessary to generate points. The texture content is estimated by a single number in the range [0, 1]. Decreasing this setting may yield more complete densification at the expense of increased noise while increasing it may yield less points especially in areas with uniform texture. The default value is recommended.

property window_size

Size of the square grid used for matching the densified points in the original images, in pixels. Possible values:

  1. Use a 7x7 pixels grid. This is suggested for aerial nadir images. The NADIR template uses this value.

  1. Use a 9x9 pixels grid. This is suggested for oblique and terrestrial images. This value is useful for more accurate positioning of the densified points in the original images. The OBLIQUE template uses this value.

class pix4dvortex.dense.Settings.TEMPLATES

Pre-defined settings for commonly used image capture types.

NADIR

Optimized for aerial nadir image capture.

OBLIQUE

Optimized for aerial oblique or terrestrial image capture.

class pix4dvortex.pcl.PointCloud(*args, **kwargs)

Composite of pix4dvortex.dmodel.GLTFPointCloud and pix4dvortex.dmodel.SceneRefFrame OPF types.

This class is a specialization of pix4dvortex.dmodel.GLTFPointCloud, with a pix4dvortex.dmodel.SceneRefFrame object and additional methods to increase usability. It is intended to model the output of a point cloud densification algorithm, with the pix4dvortex.dmodel.SceneRefFrame representing the bridge between the glTF positions - stored in the “canonical” SRS - and the “base” SRS, typically a real world “projected” SRS.

Overloaded function.

  1. __init__(self: pix4dvortex.pcl.PointCloud) -> None

  2. __init__(self: pix4dvortex.pcl.PointCloud, *, model_path: os.PathLike | str | bytes, scene_ref_frame: pix4dvortex.dmodel.SceneRefFrame | None = None) -> None

class Attribute
class Color
class Normal
class Position
COLOR = <pix4dvortex._pyext.lib._pyvtx.pcl.PointCloud.Attribute.Color object>
NORMAL = <pix4dvortex._pyext.lib._pyvtx.pcl.PointCloud.Attribute.Normal object>
POSITION = <pix4dvortex._pyext.lib._pyvtx.pcl.PointCloud.Attribute.Position object>
bounding_box(self: pix4dvortex.pcl.PointCloud) → pix4dvortex.geom.Box
camera_ids(self: pix4dvortex.pcl.PointCloud) → list[int]
copy(self: pix4dvortex.dmodel.GLTFPointCloud, *, out_dir: os.PathLike | str | bytes) → pix4dvortex.dmodel.GLTFPointCloud

Return a self-contained copy of this object.

Creates and returns a fully self-contained copy of this object. As a result, all managed GLTF files are copied.

Parameters:

out_dir – Directory to copy internal data files into.

Raises:

RuntimeError – if out_dir is the same as the parent of this object’s model_path().

empty(self: pix4dvortex.dmodel.GLTFPointCloud) → bool
hash(self: pix4dvortex.pcl.PointCloud) → int
is_partitioned(self: pix4dvortex.pcl.PointCloud, i: SupportsInt | None = None) → bool

Check if the GLTF is partitioned.

Parameters:

i – the index of the point cloud to partition. If none is passed, check if all point clouds are partitioned.

Returns:

True if partitioned.

Raises:

RuntimeError – if the index is out of range

model_path(self: pix4dvortex.dmodel.GLTFPointCloud) → pathlib.Path
partition(self: pix4dvortex.pcl.PointCloud, i: SupportsInt | None = None, min_points_per_node: SupportsInt = 64, lod_node_chunk_size: SupportsInt | None = 250000, _sorted_partitioning: bool = False) → None

Partition the GLTF for octree-based fast spatial queries.

Partitioning will reorder the content of the binary buffers in-place and update the GLTF model accordingly. If the point cloud is already partitioned, do nothing.

Parameters:

  • i – the index of the point cloud to partition. If None is passed, partition all point clouds in the GLTF.

  • min_points_per_node – Parameter controlling the stopping criterion for spatial partitioing. During octree construction, a node will stop subdividing when it contains fewer than min_points_per_node points.

  • lod_node_chunk_size – Parameter controlling the size of chunks in the level-of-detail (LoD) representation. Specifically, the LoD partitioning is designed so that nodes at the i-th depth level of the octree contain approximately lod_node_chunk_size points in the corresponding i-th LoD chunk.

  • _sorted_partitioning – If True, the partitioning algorithm will look for a custom float32 glTF attribute named “importance” in the file to partition. This will be used to create LoD chunks with decreasing values of this “importance” field.

Raises:

  • RuntimeError – if the index is out of range

  • RuntimeError – if _sorted_partitioning is True but the file has no “importance” attribute, or if lod_node_chunk_size is None.

Note

If another point cloud refers to the same buffers on disk, it will be left in an inconsistent state. Partitioning should be done before any other operation.

scene_ref_frame(self: pix4dvortex.pcl.PointCloud) → pix4dvortex.dmodel.SceneRefFrame
size(self: pix4dvortex.dmodel.GLTFPointCloud) → int
opf_type = 'point_cloud'
class pix4dvortex.pcl.PointCloud.Box
max_corner(self: pix4dvortex.geom.Box) → list
min_corner(self: pix4dvortex.geom.Box) → list

DSM/DTM

Module for dsm utilities.

class pix4dvortex.dsm.DTMSettings(self: pix4dvortex.dsm.DTMSettings, *, dsm_settings: pix4dvortex.dsm.Settings, rigidity: pix4dvortex.dsm.Rigidity = Rigidity.Medium, filter_threshold: SupportsFloat = 0.5, cloth_sampling_distance: SupportsFloat = 1.0)
to_dict(self: pix4dvortex.dsm.DTMSettings) → dict
property cloth_sampling_distance

Inter-point sampling distance used to derive simulated cloth overlying the base of the point cloud. Values in the range 1.0 to 1.5 are recommended for the majority of use cases.

property dsm_settings

DSM generation parameters.

property filter_threshold

Cut-off threshold for terrain classification. Points with height over simulated cloth surface larger than threshold are rejected. The remaining points are considered to belong to the terrain. The units of measurement are the same as those of the point cloud.

property rigidity

Tension of simulated cloth overlying the base of the point cloud.

class pix4dvortex.dsm.Settings(self: pix4dvortex.dsm.Settings, *, method: pix4dvortex.dsm.Settings.Triangulation | pix4dvortex.dsm.Settings.IDW, resolution: SupportsFloat, max_tile_size: SupportsInt = 4096, no_data_value: SupportsFloat = nan)

No data value.

class IDW(*args, **kwargs)

Recommended for urban areas, construction sites and buildings. Provides good accuracy, but can produce empty cells and outliers.

Parameters:

  • pcl_scale (float) – [Optional] The horizontal resolution of the point cloud (roughly the average/median horizontal distance between nearest neighbors). If omitted (recommended), the optimal scale is automatically estimated from the input point cloud data.

  • interpolation_nn_count (int) – [Optional] Number of nearest neighbors to use for interpolation.

  • smoothing_median_radius (int) – [Optional] Median pixel radius distance to use to smooth the output.

Note

The usage of gsd and dense_settings as input is deprecated. We recommend instead using IDW(pcl_scale, smoothing_median_radius, interpolation_nn_count) by intentionally omitting pcl_scale or setting pcl_scale=None for automatic estimation.

Overloaded function.

  1. __init__(self: pix4dvortex.dsm.Settings.IDW, *, gsd: typing.SupportsFloat, dense_settings: pix4dvortex.dense.Settings, smoothing_median_radius: typing.SupportsInt | None = 12, interpolation_nn_count: typing.SupportsInt | None = 10) -> None

  2. __init__(self: pix4dvortex.dsm.Settings.IDW, *, pcl_scale: typing.SupportsFloat | None = None, smoothing_median_radius: typing.SupportsInt | None = 12, interpolation_nn_count: typing.SupportsInt | None = 10) -> None

property interpolation_nn_count
property smoothing_median_radius
class Triangulation(self: pix4dvortex.dsm.Settings.Triangulation)

Recommended for rural areas, agriculture or low texture captures. Provides a less accurate DSM. Typically produces fewer empty cells; rare isolated gaps may appear.

to_dict(self: pix4dvortex.dsm.Settings) → dict
property max_tile_size

Desired size of the DSM tiles in pixels. Recommended range is 500-8000.

property method
property no_data_value
property resolution

The GSD value as generated by calibration. The used value must remain the same for DSM, DTM, Ortho and GeoTiff writer.

pix4dvortex.dsm.gen_dsm(*, point_cloud: pix4dvortex.pcl.PointCloud, roi: pix4dvortex.geom.Roi2D | None = None, settings: pix4dvortex.dsm.Settings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.dmodel._GeotiffView

Generate a digital surface model (DSM).

Parameters:

  • point_cloud – Input point cloud.

  • roi – (optional) Region of interest polygon or multi-polygon in XY plane.

  • settings – Configuration parameters.

  • resources – HW resource configuration parameters.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:

Note

This function differs from gen_tiled_dsm() in that it will store the output as a single file on disk.

pix4dvortex.dsm.gen_dtm(*, point_cloud: pix4dvortex.pcl.PointCloud, roi: pix4dvortex.geom.Roi2D | None = None, settings: pix4dvortex.dsm.DTMSettings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.dmodel._GeotiffView

Generate a digital terrain model (DTM).

Generate a DTM by applying a cloth simulation filter (CSF) to a digital surface model (DSM). The CSF is applied to the DSM generation on the fly, producing a DTM without need for intermediate DSM artifacts.

Parameters:

  • point_cloud – Input point cloud.

  • roi – (optional) Region of interest polygon or multi-polygon in XY plane.

  • settings – Configuration parameters.

  • resources – HW resource configuration parameters.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Cancellation callback.

Raises:

Note

This function differs from gen_tiled_dtm in that it will store the output as a single file in disk.

pix4dvortex.dsm.gen_tiled_dsm(*, point_cloud: pix4dvortex.pcl.PointCloud, roi: pix4dvortex.geom.Roi2D | None = None, settings: pix4dvortex.dsm.Settings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.dsm._DsmTiles

Generate a tiled digital surface model (DSM).

Parameters:

  • point_cloud – Input point cloud.

  • roi – (optional) Region of interest polygon or multi-polygon in XY plane.

  • settings – Configuration parameters.

  • resources – HW resource configuration parameters.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
pix4dvortex.dsm.gen_tiled_dtm(*, point_cloud: pix4dvortex.pcl.PointCloud, roi: pix4dvortex.geom.Roi2D | None = None, settings: pix4dvortex.dsm.DTMSettings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.dsm._DsmTiles

Generate a tiled digital terrain model (DTM).

Generate a DTM by applying a cloth simulation filter (CSF) to a digital surface model (DSM). The CSF is applied to the DSM generation on the fly, producing a DTM without need for intermediate DSM artifacts.

Parameters:

  • point_cloud – Input point cloud.

  • roi – (optional) Region of interest polygon or multi-polygon in XY plane.

  • settings – Configuration parameters.

  • resources – HW resource configuration parameters.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Cancellation callback.

Raises:
pix4dvortex.dsm.version() → str
class pix4dvortex.dsm.Rigidity(self: pix4dvortex.dsm.Rigidity, value: SupportsInt)
High = <Rigidity.High: 2>
Low = <Rigidity.Low: 0>
Medium = <Rigidity.Medium: 1>

Orthomosaic

Module for orthomosaic generation utilities.

pix4dvortex.ortho.gen_orthomosaic(*, cameras: collections.abc.Sequence[pix4dvortex._pyext.lib._pyvtx.cameras.CameraParameters], input_cameras: pix4dvortex.cameras.InputCameras, scene_ref_frame: pix4dvortex.dmodel.SceneRefFrame, dsm: pix4dvortex.dmodel._GeotiffView, settings: pix4dvortex.ortho.Settings, sensor_layout: pix4dvortex.ortho.SensorLayout | None = None, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.dmodel._GeotiffView

Generate orthomosaic.

Parameters:

  • cameras – List of calibrated cameras.

  • input_cameras – Input cameras object, used to obtain image data.

  • scene_ref_frame – Scene reference frame of the calibrated cameras.

  • dsm – a view of a DSM GeoTIFF, its CRS must match the base CRS of scene_ref_frame

  • settings – Configuration parameters

  • sensor_layout – (optional) single sensor layout from get_sensor_layouts(). Required when there is more than one sensor layout (for example RGB and Thermal IR). Omit when there is only one sensor layout. Skipping it does not default to RGB.

  • resources – HW resource configuration parameters. Note: use_gpu is experimental in this function and takes effect when using the fast blending algorithm (see settings). It requires Vulkan 1.2 and may have issues on NVIDIA GeForce [Ti] 1050 cards with 4GiB RAM on Windows.

  • logger – Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
Note: This function differs from gen_tiled_orthomosaic in that it takes a DSM produced by either

gen_dsm or gen_dtm and it stores the output as a single file in disk.

pix4dvortex.ortho.gen_tiled_orthomosaic(*, cameras: collections.abc.Sequence[pix4dvortex._pyext.lib._pyvtx.cameras.CameraParameters], input_cameras: pix4dvortex.cameras.InputCameras, dsm_tiles: pix4dvortex.dsm._DsmTiles, settings: pix4dvortex.ortho.Settings, sensor_layout: pix4dvortex.ortho.SensorLayout | None = None, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.ortho._OrthoTiles

Generate orthomosaic.

Parameters:

  • cameras – List of calibrated cameras.

  • input_cameras – Input cameras object, used to obtain image data.

  • dsm_tiles – List of DSM tiles.

  • settings – Configuration parameters

  • sensor_layout – (optional) a single sensor layout from get_sensor_layouts(). Required when there is more than one sensor layout (for example RGB and Thermal IR). If skipped, the processing leads to an error. The parameter may be omitted when there is only one sensor layout.

  • resources – HW resource configuration parameters. Note: use_gpu is experimental in this function and takes effect when using the fast blending algorithm (see settings). It requires Vulkan 1.2 and may have issues on NVIDIA GeForce [Ti] 1050 cards with 4GiB RAM on Windows.

  • logger – Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
pix4dvortex.ortho.get_sensor_layouts(*, cameras: collections.abc.Sequence[pix4dvortex._pyext.lib._pyvtx.cameras.CameraParameters], input_cameras: pix4dvortex.cameras.InputCameras) → list[pix4dvortex.ortho.SensorLayout]

List the sensor layouts that can be used for orthomosaic generation.

A sensor layout is the set of sensors that belong in one orthomosaic run.

Typical cases:

  • RGB only, Thermal IR only, or multispectral only: one sensor layout; run orthomosaic once.

  • RGB + Thermal IR: two sensor layouts; run orthomosaic twice, once per layout. Cameras are calibrated together, but each layout needs its own orthomosaic run and cannot be combined in one.

Pass one item from this list as sensor_layout to gen_orthomosaic() / gen_tiled_orthomosaic() (or the fastalgo equivalents).

If there is only one sensor layout, you may omit sensor_layout. Use band_types() to tell two sensor layouts apart, for example Red, Green, Blue vs Thermal IR.

Parameters:

  • cameras – List of calibrated cameras.

  • input_cameras – Input cameras object.

Returns:

A list of SensorLayout.

pix4dvortex.ortho.version() → str
class pix4dvortex.ortho.Settings(self: pix4dvortex.ortho.Settings, *, fill_occlusion_holes: bool = True, blend_ratio: SupportsFloat = 0.10000000149011612, pipeline: pix4dvortex.ortho.Settings.Pipeline = Pipeline.FAST, capture_pattern: pix4dvortex.ortho.Settings.CapturePattern = CapturePattern.NADIR, pan_sharpening: bool = False, tile_size: SupportsInt | None = None)

Configuration of the orthomosaic generation algorithm.

Parameters:

  • fill_occlusion_holes – If True, fill occlusion holes (areas not captured on camera) with the pixels of the nearest image.

  • blend_ratio – Coefficient determining the size of the area to be blended at the borders of image patches. More details at blend_ratio.

  • pipeline – Type of the algorithmic pipeline (Pipeline).

  • capture_pattern – Type of the capture pattern (CapturePattern).

  • pan_sharpening – If True, enable pan sharpening (requires a panchromatic band).

  • tile_size (optional) – If given, override automatic processing tile size selection with a user choice. Only used by gen_orthomosaic(), ignored by gen_tiled_orthomosaic(), for ground mesh-based orthos it is accepted by both gen_tiled_orthomosaic() and gen_orthomosaic().

to_dict(self: pix4dvortex.ortho.Settings) → dict
property blend_ratio

Coefficient determining the size of the area to be blended at the borders of image patches. The value should be in the range 0.0 to 1.0. Value 0.0 means no blending, leading to hard borders. Value 1.0 means full blending of the two nearest images. Values in the range 0.1 to 0.2 are recommended for the majority of use cases.

property capture_pattern

Type of the capture pattern (CapturePattern).

property fill_occlusion_holes

If True, fill occlusion holes (areas not captured on camera) with the pixels of the nearest image.

property pan_sharpening

If True, enable pan sharpening (requires a panchromatic band)

property pipeline

Type of the algorithmic pipeline (Pipeline).

property tile_size

If not None, overrides automatic processing tile size selection with a user choice. Only used by gen_orthomosaic(), ignored by gen_tiled_orthomosaic(), for Fastortho algorithms it is accepted by both gen_tiled_orthomosaic() and gen_orthomosaic().

class pix4dvortex.ortho.Settings.TEMPLATES

Pre-defined settings for commonly used image capture types.

NADIR

Optimized for aerial nadir image capture and for the highest processing speed. Prefer this template after calibrate(), which is a 2D / nadir algorithm for flat terrain.

DEGHOST

Optimized for nadir captures where moving objects (moving during the capture) should be removed.

OBLIQUE

Optimized for aerial and terrestrial oblique image captures.

class pix4dvortex.ortho.Settings.Pipeline(self: pix4dvortex.ortho.Settings.Pipeline, value: SupportsInt)

Type of the algorithmic pipeline to use for the orthomosaic generation.

DEGHOST = <Pipeline.DEGHOST: 2>

Pipeline targeted at removal of moving (during capture) objects. Algorithmically based on the FULL pipeline.

FAST = <Pipeline.FAST: 0>

Best performance and detail-tuned algorithm for use with nadir captures.

FULL = <Pipeline.FULL: 1>

All-purpose or fallback algorithm, obligatory for oblique cameras.

class pix4dvortex.ortho.Settings.CapturePattern(self: pix4dvortex.ortho.Settings.CapturePattern, value: SupportsInt)

Type of photography used for image capture.

NADIR = <CapturePattern.NADIR: 0>

Nadir photography.

OBLIQUE = <CapturePattern.OBLIQUE: 1>

Oblique photography.

class pix4dvortex.ortho.SensorLayout

Layout for one sensor (for example RGB, Thermal IR) to pass as sensor_layout to a single orthomosaic run.

If the project has two sensor layouts (for example RGB and Thermal IR), the orthomosaic process must run once for each sensor layout and pass this object in sensor_layout. If there is only one sensor layout (datasets: RGB only, multispectral rig only, or thermal only), you may omit the parameter.

Use get_sensor_layouts() to list the available sensor layouts. band_types() tells them apart (Red, Green, Blue vs Thermal IR vs Red, Green, RedEdge, NIR).

band_types(self: pix4dvortex.ortho.SensorLayout) → list[str]

Band types in this layout (for example Red, Green, Blue or Thermal IR).

3D Mesh

Module for mesh utilities.

pix4dvortex.mesh.gen_mesh(*, settings: pix4dvortex.mesh.ScalableSettings, point_cloud: pix4dvortex.pcl.PointCloud, calibrated_cameras: pix4dvortex.dmodel.CalibratedCameras, input_cameras: pix4dvortex.cameras.InputCameras, silhouette_mask_map: collections.abc.Mapping[SupportsInt, os.PathLike | str | bytes] = {}, texture_mask_map: collections.abc.Mapping[SupportsInt, os.PathLike | str | bytes] = {}, _depth_raster_map: collections.abc.Mapping[SupportsInt, os.PathLike | str | bytes] = {}, roi: pix4dvortex.geom.Roi3D | None = None, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.mesh._MeshLOD

Generate a high quality level of detail (LOD) textured mesh using a scalable, memory efficient algorithm.

Generate an LOD textured mesh using an out-of-core algorithm that provides higher quality outputs than the combination of gen_mesh_geometry, gen_mesh_texture and gen_textured_mesh_lod at the expense of increased computational time.

The algorithm produces independent high resolution tiles that for are post-processed to produce a LOD representation. The out-of-core representation will be stored in resources.work_dir and must be retained to keep the returned object valid.

Geometrical constraints can be optionally defined either by depth and depth confidence information contained in input cameras, by externally provided depth maps or by silhouette masks. When the depth maps are externally provided, the depth and confidence maps coming from the input cameras are ignored.

The texture settings are applied to the generation of the mesh tile texture. Texture masks may be provided to discard image pixels when generating the texture.

Both silhouette and texture masks must have the same size as the camera image to which they map. The masks will be read as single channel 8-bit images. Pixels with a value greater than 0 are masked.

The depth maps can a have a size smaller or equal than the camera image to which they map. The depth maps will be read as single channel floating point images. A special value of zero can be assigned to the depth map pixels to ignore them.

Parameters:

  • settings – Configuration parameters of type ScalableSettings. See also SCALABLE_MESH_TEMPLATES.

  • point_cloud – Densified point cloud.

  • calibrated_cameras – Calibrated cameras object

  • input_cameras – Input cameras object, for accessing RGB and maybe depth information associated to images.

  • silhouette_mask_map – (optional) Mapping of a camera ID to the path of an associated silhouette mask file. The camera ID corresponds to camera.id, where camera is an element of the cameras parameter.

  • texture_mask_map – (optional) Mapping of a camera ID to the path of an associated texture mask file. The camera ID corresponds to camera.id, where camera is an element of the cameras parameter.

  • _depth_raster_map – (optional) Mapping of a camera ID to the path of an associated depth raster file. The camera ID corresponds to camera.id, where camera is an element of the cameras parameter.

  • roi – (optional) Region of interest that, when provided, will restrict mesh generation to the specified region, which can improve quality for specific areas of interest.

  • resources – (optional) HW resource configuration parameters of type Resources.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Progress callback.

  • stop_function – (optional) Cancellation callback.

Raises:
Returns:

An LOD mesh object.

pix4dvortex.mesh.gen_mesh_geometry(*, point_cloud: pix4dvortex.pcl.PointCloud, settings: pix4dvortex.mesh.Settings, cameras: collections.abc.Sequence[pix4dvortex._pyext.lib._pyvtx.cameras.CameraParameters], input_cameras: pix4dvortex.cameras.InputCameras | None = None, mask_map: collections.abc.Mapping[SupportsInt, os.PathLike | str | bytes] = {}, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.mesh._MeshGeom

Generate mesh geometry defining vertices (as x,y,z coordinates) and faces of a mesh.

Constraints can be optionally defined either by depth and depth confidence information contained in input cameras or by masks.

Parameters:

  • point_cloud – Densified point cloud.

  • settings – Configuration parameters of type Settings.

  • cameras – List of calibrated cameras.

  • input_cameras – (optional) Input cameras object, for accessing depth information associated to images.

  • mask_map – (optional) Mapping of a camera ID to the path of an associated mask file. The camera ID corresponds to camera.id, where camera is an element of the cameras parameter.

  • resources – (optional) HW resource configuration parameters of type Resources.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
Returns:

A mesh geometry object.

pix4dvortex.mesh.gen_mesh_texture(*, mesh_geom: pix4dvortex.mesh._MeshGeom, cameras: collections.abc.Sequence[pix4dvortex._pyext.lib._pyvtx.cameras.CameraParameters], input_cameras: pix4dvortex.cameras.InputCameras, settings: pix4dvortex.mesh.TextureSettings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.mesh._Texture

Generate mesh texture.

Parameters:

  • mesh_geom – Mesh geometry that defines vertices (as x,y,z coordinates) and faces of a mesh.

  • cameras – List of calibrated cameras.

  • input_cameras – Input cameras object.

  • settings – Configuration parameters of type TextureSettings.

  • resources – (optional) HW resource configuration parameters of type Resources.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
Returns:

A mesh texture object.

pix4dvortex.mesh.gen_textured_mesh_lod(*, mesh_geom: pix4dvortex.mesh._MeshGeom, texture: pix4dvortex.mesh._Texture, settings: pix4dvortex.mesh.LODSettings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.mesh._MeshLOD

Generate a level of detail (LOD) textured mesh.

Parameters:

  • mesh_geom – Mesh geometry that defines vertices (as x,y,z coordinates) and faces of a mesh.

  • texture – Mesh texture opaque data container.

  • settings – LOD configuration parameters of type LODSettings.

  • resources – (optional) HW resource configuration parameters of type Resources. Only max_threads is used.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Progress callback.

  • stop_function – (optional) Cancellation callback.

Raises:
Returns:

An LOD mesh object.

pix4dvortex.mesh.version() → str
class pix4dvortex.mesh.SCALABLE_MESH_TEMPLATES

Pre-defined settings for commonly used image capture types.

Contains definitions of objects of type ScalableSettings, tuned for different image capture types.

CATCH

Defaults for PIX4Dcatch projects.

OBLIQUE

Defaults for Oblique projects.

NADIR

Defaults for Nadir projects.

class pix4dvortex.mesh.ScalableSettings

Configuration of the scalable mesh generation algorithm.

class pix4dvortex.mesh.Settings(self: pix4dvortex.mesh.Settings, *, _geom_gen: pix4dvortex.mesh.Settings._GeomGen = pix4dvortex.mesh.Settings._GeomGen(), _constraints: pix4dvortex.mesh.Settings._Constraints = pix4dvortex.mesh.Settings._Constraints(), _small_comp_filter: pix4dvortex.mesh.Settings._SmallCompFilter = pix4dvortex.mesh.Settings._SmallCompFilter(), _decimation: pix4dvortex.mesh.Settings._Decimation = pix4dvortex.mesh.Settings._Decimation(), _smoothing: pix4dvortex.mesh.Settings._Smoothing = pix4dvortex.mesh.Settings._Smoothing())

Configuration of the mesh geometry generation algorithm.

to_dict(self: pix4dvortex.mesh.Settings) → dict
class pix4dvortex.mesh.Settings.TEMPLATES

Pre-defined settings for commonly used image capture types.

LARGE

Optimized for large scenes and aerial nadir image capture.

SMALL

Optimized for small scenes and aerial oblique or terrestrial image capture.

TOWER

Optimized for tower-like structures.

class pix4dvortex.mesh.TextureSettings(self: pix4dvortex.mesh.TextureSettings, *, _outlier_threshold: SupportsFloat = 0.009999999776482582, _texture_size: SupportsInt | None = None)

Configuration of the texture generation algorithm.

to_dict(self: pix4dvortex.mesh.TextureSettings) → dict
class pix4dvortex.mesh.TextureSettings.TEMPLATES

Pre-defined settings for different quality of geometry reconstruction and image capture.

STANDARD

Optimized for well-reconstructed geometries and image captures with no or few occluding or moving features.

DEGHOST

Optimized for imperfect geometries and image captures with many occluding or moving features.

class pix4dvortex.mesh.LODSettings(self: pix4dvortex.mesh.LODSettings, *, _max_n_faces_per_node: SupportsInt = 100000, _texture_size: SupportsInt = 1024, _jpeg_quality: SupportsInt = 90)

Configuration of the LOD mesh generation algorithm.

to_dict(self: pix4dvortex.mesh.LODSettings) → dict
class pix4dvortex.mesh._Texture
class pix4dvortex.mesh._MeshGeom
class pix4dvortex.mesh._MeshLOD

Level of detail representation of a textured mesh

Fast calibration and Orthomosaic generation

Fast calibration and orthomosaic generation utilities.

pix4dvortex.fastalgo.calibrate(*, cameras: pix4dvortex.cameras.ProjectedCameras, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.calib._CalibratedScene

Generate calibrated scene with fast calibration algorithm.

This algorithm is optimized for nadir data captures on flat terrain. The algorithm produces a calibrated scene with a surface model mesh in lieu of a densified point cloud, and can be used directly to generate an orthomosaic with gen_tiled_orthomosaic() and gen_orthomosaic().

Parameters:

  • cameras – Projected cameras container.

  • resources – HW resource configuration parameters.

  • logger – Logging callback.

  • progress_callback – Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
Returns:

A calibrated scene with ground mesh and no sparse point cloud. See _CalibratedScene.

pix4dvortex.fastalgo.gen_orthomosaic(*, scene: pix4dvortex.calib._CalibratedScene, input_cameras: pix4dvortex.cameras.InputCameras, settings: pix4dvortex.ortho.Settings, sensor_layout: pix4dvortex.ortho.SensorLayout | None = None, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.dmodel._GeotiffView

Generate orthomosaic from fast calibration output.

Generate orthomosaic from a calibrated scene containing a ground mesh, as generated with calibrate().

Favour NADIR template as settings. Fast calibration is a 2D / nadir algorithm for flat terrain. The OBLIQUE is technically usable but neither recommended, suitable or beneficial for this pipeline.

Parameters:

  • scene – A calibrated scene containing a ground mesh.

  • input_cameras – Input cameras object, used to obtain image data.

  • settings – Configuration parameters. Prefer NADIR.

  • sensor_layout – (technically optional) user selection of single sensor layout from get_sensor_layouts(). Required when there is more than one sensor layout (for example RGB + Thermal IR). It is irrelevant when there is only one.

  • resources – HW resource configuration parameters. Note: use_gpu is experimental in this function and takes effect when using the fast blending algorithm (see settings). It requires Vulkan 1.2 and may have issues on older NVIDIA GPUs or with low GPU RAM.

  • logger – Logging callback.

  • progress_callback – Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:

Note

This function differs from gen_tiled_orthomosaic in that it will store the output as a single file in disk.

pix4dvortex.fastalgo.gen_tiled_orthomosaic(*, scene: pix4dvortex.calib._CalibratedScene, input_cameras: pix4dvortex.cameras.InputCameras, settings: pix4dvortex.ortho.Settings, sensor_layout: pix4dvortex.ortho.SensorLayout | None = None, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.ortho._OrthoTiles

Generate orthomosaic from fast calibration output.

Generate orthomosaic from a calibrated scene containing a ground mesh, as generated with calibrate().

Favour NADIR template as settings. Fast calibration is a 2D / nadir algorithm for flat terrain. The OBLIQUE is technically usable but neither recommended, suitable or beneficial for this pipeline.

Parameters:

  • scene – A calibrated scene containing a ground mesh.

  • input_cameras – Input cameras object, used to obtain image data.

  • settings – Configuration parameters. Prefer NADIR.

  • sensor_layout – (technically optional) user selection of single sensor layout from get_sensor_layouts(). Required when there is more than one sensor layout (for example RGB + Thermal IR). It is irrelevant when there is only one.

  • resources – HW resource configuration parameters. Note: use_gpu is experimental in this function and takes effect when using the fast blending algorithm (see settings). It requires Vulkan 1.2 and may have issues on older NVIDIA GPUs or with low GPU RAM.

  • logger – Logging callback.

  • progress_callback – Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
pix4dvortex.fastalgo.version() → str

Gaussian Splatting

Module for Gaussian splatting utilities.

class pix4dvortex.gsplat.RasterSettings(self: pix4dvortex.gsplat.RasterSettings, pixel_size: SupportsFloat, no_data_value: SupportsFloat = nan, interpolate_dsm: bool = True)

Configuration of the rasterization process

property interpolate_dsm

Whether to interpolate no-data pixels or not. Only no-data pixels inside the convex hull of the rasterized model will be interpolated, or inside the region of interest if provided. Default is True.

property no_data_value

Value used to fill no-data pixels. Default is NaN.

property pixel_size

Pixel size of the output rasters (typically GSD) in units of the processing CRS.

pix4dvortex.gsplat.gen_gs(*, point_cloud: pix4dvortex.pcl.PointCloud, settings: pix4dvortex.gsplat.Settings, calibrated_cameras: pix4dvortex.dmodel.CalibratedCameras, input_cameras: pix4dvortex.cameras.InputCameras, mask_map: collections.abc.Mapping[SupportsInt, os.PathLike | str | bytes] | None = None, roi: pix4dvortex.geom.Roi3D | None = None, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None, _metrics_callback: collections.abc.Callable[[str], None] = None) → tuple[pix4dvortex.gsplat.GaussianSplatting, pix4dvortex.pcl.PointCloud | None, dict[int, pix4dvortex.cameras.DepthInfo] | None]

Generate a Gaussian splatting model.

Generate a Gaussian splatting model from a partitioned input point cloud. The model is stored on disk using the format from the OPF extension PIX4D_gaussian_splatting. Refer to the specification for details about how to render the model.

The algorithm can optionally produce a point cloud and synthetic depth maps derived from the model. This can be adjusted in the settings. Note that these artifacts cannot be produced as a post-processing step, the only chance to produce them is during model generation.

Additional constraints can be defined by depth and depth confidence information contained in input cameras and by sky masks.

The depth/confidence maps provide geometrical constraints. The depth maps can have a size smaller or equal than the camera image to which they map. The depth maps will be read as single channel floating point images. Zero is a special value that indicates that a pixel has to be ignored. For any camera for which a depth map is provided, a confidence map must be provided as well. The confidence maps are single channel unsigned 8-bit rasters whose size must be equal to the pairing depth map. Any depth pixel with a confidence value smaller than 2 will be ignored.

Sky masks are unsigned 8-bit rasters that must be the same size as the input images. Each pixel can take a value either 0 (unmasked) or 255 (masked). The algorithm tries to produce Gaussians that project as little as possible on masked pixels. This is useful for removing floaters due to the sky.

Parameters:

  • settings – Configuration parameters of type Settings.

  • point_cloud – Densified and partitioned point cloud.

  • calibrated_cameras – Calibrated cameras object.

  • input_cameras – Input cameras object, for accessing RGB and maybe depth information associated to images.

  • mask_map – (optional) Mapping of a camera ID to the path of an associated mask file. The camera ID corresponds to camera.id, where camera is an element of the ìnput_cameras parameter.

  • roi – (optional) Region of interest to constrain the generation. The ROI is defined as a 2D polygon with min and max elevation constraints, in scene coordinates.

  • resources – (optional) HW resource configuration parameters of type Resources.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Progress callback.

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
Returns:

A tuple of a pix4dvortex.gsplat.GaussianSplatting object, a PointCloud and synthetic depth maps. The point cloud is None if and only if settings.compute_point_cloud is False. The synthetic depth maps is None if and only if settings.compute_depth_maps is False. The format of the depth maps is a dictionary mapping each camera ID to the corresponding DepthInfo.

pix4dvortex.gsplat.gen_gs_dsm(*, gs_model: pix4dvortex.gsplat.GaussianSplatting, settings: pix4dvortex.gsplat.RasterSettings, resources: pix4dvortex.proc.Resources = None, roi: pix4dvortex.geom.Roi3D | None = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None, logger: collections.abc.Callable[[SupportsInt, str], None] = None, _metrics_callback: collections.abc.Callable[[str], None] = None) → pix4dvortex.dmodel._GeotiffView

Generate a digital surface model (DSM) from a Gaussian splatting model at a given pixel size.

The algorithm projects and rasterizes a Gaussian splatting model from its 3D space onto a digital surface model (DSM).

Parameters:

  • gs_model – Gaussian splatting model of type GaussianSplatting. It must possess a valid scene reference frame to align the model from its canonical reference system.

  • settings – Configuration parameters of type RasterSettings.

  • resources – (optional) HW resource configuration parameters of type Resources with work_dir, max_threads and max_gpu_mem parameters.

  • roi – (optional) Region of interest to constrain the rasterization, of type Roi3D (the ROI is defined as a 2D polygon with min and max elevation constraints, in base coordinates of the scene reference frame of gs_model).

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Progress callback.

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
Returns:

A DSM object of type _GeotiffView.

pix4dvortex.gsplat.version() → str
class pix4dvortex.gsplat.Settings

Configuration of the Gaussian splatting model generation.

static from_preset(*, preset: pix4dvortex.gsplat.Presets) → pix4dvortex.gsplat.Settings
to_dict(self: pix4dvortex.gsplat.Settings) → dict
property compute_depth_maps

Whether to generate depth maps from the Gaussian splatting model or not. True by default.

property compute_point_cloud

Whether to generate a point cloud from the Gaussian splatting model or not. True by default.

property preset
class pix4dvortex.gsplat.Settings.TEMPLATES

Pre-defined settings for commonly used image capture types.

Contains definitions of objects of type Settings, tuned for different image capture types.

TERRESTRIAL

Defaults for PIX4Dcatch projects.

DRONE

Defaults for drone projects.

MIXED_DRONE_TERRESTRIAL

Defaults for projects mixing images from PIX4Dcatch and drones.

class pix4dvortex.gsplat.Presets(self: pix4dvortex.gsplat.Presets, value: SupportsInt)
DRONE = <Presets.DRONE: 1>
MIXED_DRONE_TERRESTRIAL = <Presets.MIXED_DRONE_TERRESTRIAL: 2>
TERRESTRIAL = <Presets.TERRESTRIAL: 0>
class pix4dvortex.gsplat.GaussianSplatting(self: pix4dvortex.gsplat.GaussianSplatting, *, model_path: os.PathLike | str | bytes, scene_ref_frame: pix4dvortex.dmodel.SceneRefFrame | None = None)

Composite of pix4dvortex.dmodel.GLTFGSplat and pix4dvortex.dmodel.SceneRefFrame OPF types.

This class is a specialization of pix4dvortex.dmodel.GLTFGSplat, with a pix4dvortex.dmodel.SceneRefFrame object and additional methods to increase usability. It is intended to model the output of a Gaussian splatting generation algorithm, with the pix4dvortex.dmodel.SceneRefFrame representing the bridge between the glTF positions - stored in the “canonical” SRS - and the “base” SRS, typically a real world “projected” SRS.

bounding_box(self: pix4dvortex.gsplat.GaussianSplatting) → pix4dvortex.geom.Box
hash(self: pix4dvortex.gsplat.GaussianSplatting) → int
scene_ref_frame(self: pix4dvortex.gsplat.GaussianSplatting) → pix4dvortex.dmodel.SceneRefFrame
opf_type = 'ext_pix4d_gaussian_splatting'

More Processing

AutoGCP

Automatic GCP detection tools.

AutoGCPs consists of a set of tools for the automatic detection in images of control point targets with pixel level accuracy.

It supports three types of targets with black and white Haar-like features: square, diagonal and Aeropoint.

Despite its name, AutoGCPs imposes no restrictions on the use of targets. The functionality only concerns itself with the detection of targets in images and the obtainment of an accurate estimate of the position of their marker. The user can then use the information as ground control points (GCPs), check-points (CPs) or anything else.

exception pix4dvortex.autogcp.AutogcpError
class pix4dvortex.autogcp.Settings(self: pix4dvortex.autogcp.Settings, *, xy_uncertainty: SupportsFloat = 5.0, z_uncertainty: SupportsFloat = 10.0)

GCP detection algorithm settings.

Parameters:

  • xy_uncertainty – Absolute horizontal image georeferencing uncertainty.

  • z_uncertainty – Absolute vertical image georeferencing uncertainty.

Note

  • The units of the uncertainties are the same as those of the input GCP geolocation.

  • The default values are optimized in meters and should be scaled accordingly if other units are used.

to_dict(self: pix4dvortex.autogcp.Settings) → dict
property xy_uncertainty

Absolute horizontal image georeferencing uncertainty.

property z_uncertainty

Absolute vertical image georeferencing uncertainty.

pix4dvortex.autogcp.detect_gcp_marks(*, scene: pix4dvortex.calib._CalibratedScene, input_cameras: pix4dvortex.cameras.InputCameras, input_gcps: collections.abc.Sequence[pix4dvortex.dmodel.GCP], settings: pix4dvortex.autogcp.Settings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → list[pix4dvortex.dmodel.GCP]

Detect GCP marks in images.

Parameters:

  • scene – Calibrated scene.

  • input_cameras – Input cameras object, used to obtain image data.

  • input_gcps – 3D GCP without marks. The GCP coordinates must be in the same coordinate system as the one used to create the projected cameras used as input to camera calibration.

  • settings – Configuration parameters.

  • resources – Hardware resources configuration parameters.

  • logger – Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Returns:

A list of GCP objects with detected marks.

Raises:

  • ValueError – if input_gcps contain marks.

  • ValueError – if input_gcps and scene CRS is not the same.

  • AutogcpError – if configuration parameters are invalid or the detection algorithm cannot complete.

pix4dvortex.autogcp.version() → str

Version of the PIX4D autogcp algorithm API.

Depth Processing

Utilities to process LiDAR and synthetic depth maps and depth point clouds.

class pix4dvortex.depth.DepthCompletionSettings(self: pix4dvortex.depth.DepthCompletionSettings, _initial_dilation_kernel_size: SupportsInt = 5, _closing_kernel_size: SupportsInt = 5, _hole_filling_kernel_size: SupportsInt = 7, _smoothing: bool = False)

Configuration parameters for depth map densification algorithm.

to_dict(self: pix4dvortex.depth.DepthCompletionSettings) → dict
class pix4dvortex.depth.MergeSettings(self: pix4dvortex.depth.MergeSettings, _distance: SupportsFloat = 0.025, _n_neighbors: SupportsInt = 128, _sor: pix4dvortex.depth.MergeSettings._SOR | None = pix4dvortex.depth.MergeSettings._SOR())
to_dict(self: pix4dvortex.depth.MergeSettings) → dict
pix4dvortex.depth.densify(*, settings: pix4dvortex.depth.DepthCompletionSettings = pix4dvortex.depth.DepthCompletionSettings(), sparse_depth_maps: collections.abc.Mapping[SupportsInt, pix4dvortex.cameras.DepthInfo], resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None) → dict[int, pix4dvortex.cameras.DepthInfo]

Generate densified depth maps from sparse depth maps.

Parameters:

  • settings – The algorithm settings, see DepthCompletionSettings.

  • sparse_depth_maps – A dictionary mapping each camera ID to its corresponding DepthInfo. The depth maps is assumed to use 0 to mark unknown depth and positive values for known depths. The confidence is ignored by this algorithm.

  • resources – HW resource configuration parameters.

  • logger – Logging callback.

Returns:

The densified depth maps, a dictionary mapping each camera ID to its corresponding DepthInfo.

pix4dvortex.depth.gen_pcl(*, settings: pix4dvortex.depth.Settings = pix4dvortex.depth.Settings(), scene: pix4dvortex.calib._CalibratedScene, input_cameras: pix4dvortex.cameras.InputCameras, roi: pix4dvortex.geom.Roi2D | None = None, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.pcl.PointCloud

Generate a depth point cloud from LiDAR depth maps.

Parameters:

  • settings – Configuration parameters, see Settings.

  • scene – Calibrated scene.

  • input_cameras – Input cameras object containing depth maps and, optionally, their confidences.

  • roi – (optional) 2D region of interest in the XY plane defined as a polygon or a muti-polygon.

  • resources – HW resource configuration parameters.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Raises:
Returns:

A point cloud object.

pix4dvortex.depth.pcl_merge(*, pcl: pix4dvortex.pcl.PointCloud, depth_pcl: pix4dvortex.pcl.PointCloud, settings: pix4dvortex.depth.MergeSettings = pix4dvortex.depth.MergeSettings(), resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex.pcl.PointCloud

Merge a densified photogrammetry point cloud with a depth point cloud created from LiDAR depth maps.

Parameters:

  • pcl – Dense point cloud.

  • depth_pcl – Depth point cloud.

  • settings – Configuration parameters, see MergeSettings.

  • resources – HW resource configuration parameters.

  • logger – (optional) Logging callback.

  • progress_callback – (optional) Progress callback.

  • stop_function – (optional) cancellation callback.

Raises:
Returns:

A point cloud object.

pix4dvortex.depth.version() → str
class pix4dvortex.depth.Settings(self: pix4dvortex.depth.Settings, *, _pcl: pix4dvortex.depth.Settings._PCL = pix4dvortex.depth.Settings._PCL(), _depth_filter: pix4dvortex.depth.Settings._DepthFilter | None = pix4dvortex.depth.Settings._DepthFilter())
to_dict(self: pix4dvortex.depth.Settings) → dict
class pix4dvortex.depth.Settings.ConfidenceLevel(self: pix4dvortex.depth.Settings.ConfidenceLevel, value: SupportsInt)
High = <ConfidenceLevel.High: 2>
Low = <ConfidenceLevel.Low: 0>
Medium = <ConfidenceLevel.Medium: 1>

Sky and Water Segmentation

Module for sky and water segmentation utilities.

pix4dvortex.skyseg.gen_segment_masks(*, cameras: collections.abc.Sequence[pix4dvortex._pyext.lib._pyvtx.cameras.CameraParameters], input_cameras: pix4dvortex.cameras.InputCameras, output_dir: os.PathLike | str | bytes, settings: pix4dvortex.skyseg.Settings, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → dict[int, pathlib.Path]

Mask sky, water or both in images.

Parameters:

  • cameras – List of calibrated cameras.

  • input_cameras – Input cameras object, used to obtain image data.

  • output_dir – Directory the mask image files will be written to.

  • settings – Configuration parameters, see Settings.

  • resources – HW resource configuration parameters.

  • logger – Logging callback.

  • progress_callback – Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Returns:

Mapping of a camera ID to the path of the mask corresponding to this image. A mask is a single-channel black-and-white image. White areas are masked.

Raises:
pix4dvortex.skyseg.version() → str

Version of the PIX4D skyseg algorithm API.

class pix4dvortex.skyseg.Settings(self: pix4dvortex.skyseg.Settings, *, masking_type: pix4dvortex.skyseg.Settings.MaskingType = MaskingType.SKY, mode: pix4dvortex.skyseg.Settings.Mode = Mode.FULL)
to_dict(self: pix4dvortex.skyseg.Settings) → dict
property masking_type

Select which entities to mask in images, see MaskingType.

property mode

Select segmentation mode, see Mode.

class pix4dvortex.skyseg.Settings.MaskingType(self: pix4dvortex.skyseg.Settings.MaskingType, value: SupportsInt)
SKY = <MaskingType.SKY: 0>

Identifies sky segments.

SKY_WATER = <MaskingType.SKY_WATER: 2>

Identifies both sky and water segments.

WATER = <MaskingType.WATER: 1>

Identifies water segments.

class pix4dvortex.skyseg.Settings.Mode(self: pix4dvortex.skyseg.Settings.Mode, value: SupportsInt)
FAST = <Mode.FAST: 1>

Fast segmentation mode. This option is faster. It is not recommended for images with water segment.

FULL = <Mode.FULL: 0>

Full segmentation mode.

Point Cloud Alignment

Utilities for obtaining a point cloud alignment.

pix4dvortex.pcalign.alignment(*, point_cloud: pix4dvortex.pcl.PointCloud, ref_point_cloud: pix4dvortex.pcl.PointCloud, logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → pix4dvortex._pyext.lib._pyvtx.pcalign.Alignment

Get an alignment of a misaligned point cloud to a reference point cloud.

Parameters:

  • point_cloud – Misaligned point cloud.

  • ref_point_cloud – Reference point cloud.

  • logger – Logging callback.

  • progress_callback – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

Returns:

Object containing a 4-by-4 transformation matrix, aligning the misaligned point cloud to the reference, and the quality of the obtained alignment.

Raises:

RuntimeError – if the spatial reference of the misaligned and the reference point clouds is not the same.

pix4dvortex.pcalign.version() → str

Version of the pcalign algorithm API.

Point Cloud Transformation

pix4dvortex.transform.transform(*args, **kwargs)

Overloaded function.

  1. transform(*, transformation: collections.abc.Buffer, point_cloud: pix4dvortex.pcl.PointCloud, work_dir: os.PathLike | str | bytes = PosixPath(‘/tmp’)) -> pix4dvortex.pcl.PointCloud

Transform a point cloud.

Parameters:

  • transformation – 4-by-4 transformation matrix to apply.

  • point_cloud – Point cloud to transform.

  • work_dir – Temporary work space. It will be created if it doesn’t exist. Defaults to system temporary directory.

Note

The spatial reference of the transformation must match that of the point cloud.

Returns:

Transformed point cloud.

  1. transform(*, transformation: collections.abc.Buffer, calib_scene: pix4dvortex.calib._CalibratedScene, work_dir: os.PathLike | str | bytes = PosixPath(‘/tmp’)) -> pix4dvortex.calib._CalibratedScene

Transform a calibrated scene.

Parameters:

  • transformation – 4-by-4 transformation matrix to apply.

  • calib_scene – Calibrated scene to transform.

Note

The spatial reference of the transformation must match that of the calibrated scene.

Returns:

Transformed calibrated scene.

Index Calculation

Orthomosaic index map generation utilities.

pix4dvortex.indexmap.compute_custom_index(*, input_path: os.PathLike | str | bytes, formula: str, output_path: os.PathLike | str | bytes) → None

Generate an index map by applying a formula to an ortho-mosaic.

Generate a GeoTIFF file containing an index map generated by applying a formula to an input ortho-mosaic. The input must be georeferenced with a CRS convertible to WGS84.

Parameters:

  • input_path – Path to a georeferenced GeoTIFF file containing an orthomisaic with bands to be used for index calculation.

  • formula – A formula to calculate index values from band values.

  • output_path – Path to a GeoTIFF file containing the index map.

Raises:

  • ValueError – if input_path does not point to a valid GeoTIFF file.

  • ValueError – if formula is not correct.

  • RuntimeError – if input is not georeferenced and convertible to WGS84.

  • RuntimeError – for any other errors.

pix4dvortex.indexmap.get_custom_index_band_names(*, path: os.PathLike | str | bytes) → list[str]

Get a list of index band names to use in index calculation formulas.”

Parameters:

path – Path to a GeoTIFF file containing an orthomisaic with bands information.

Raises:

ValueError – if path does not point to a valid GeoTIFF file.

Exports

Cesium

Utilities for exporting mesh data to Cesium format.

pix4dvortex.io.cesium.version() → str
pix4dvortex.io.cesium.write_mesh(*, output_path_prefix: os.PathLike | str | bytes, mesh_lod: pix4dvortex.mesh._MeshLOD, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None) → None

Write an LOD mesh as Cesium 3D Tiles 1.0.

Serialize an LOD mesh to the Cesium 3D Tiles file format. The output’s transform property transforms from the tile’s local coordinate system to a target depending on the SRS of the input LOD mesh: input SRS or EPSG:4978 for engineering or projected SRS respectively.

Parameters:

  • output_path_prefix – Path to the output files ending with a file name prefix.

  • mesh_lod – LOD mesh.

  • resources – Hardware resources. Only work_dir is used.

  • logger – (optional) Logging callback.

pix4dvortex.io.cesium.write_pcl(*, output_path_prefix: os.PathLike | str | bytes, point_cloud: pix4dvortex.pcl.PointCloud, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None) → None

Write a point cloud as Cesium 3D Tiles.

Serialize a point cloud to the Cesium 3D Tiles file format. The output’s transform property transforms from the tile’s local coordinate system to a target depending on the SRS of the input point cloud: input SRS or EPSG:4978 for engineering or projected SRS respectively.

Parameters:

  • output_path_prefix – Path to the output files ending with a file name prefix.

  • point_cloud – PointCloud object to be serialized.

  • resources – Hardware resources. Only max_threads and work_dir are used.

FBX

Utilities for exporting mesh data to FBX format.

pix4dvortex.io.fbx.export_levels_face_count(*, mesh_lod: pix4dvortex.mesh._MeshLOD) → dict[int, int]

Return the number of faces of each non-empty LOD level generated when the exporting mesh_lod.

Parameters:

mesh_lod – LOD mesh.

pix4dvortex.io.fbx.version() → str
pix4dvortex.io.fbx.write_mesh(*, output_path: os.PathLike | str | bytes, mesh_lod: pix4dvortex.mesh._MeshLOD, settings: pix4dvortex.io.fbx.Settings = pix4dvortex.io.fbx.Settings(), resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → None

Write a triangular LOD mesh into a FBX file.

Parameters:

  • output_path – Path to the output file.

  • mesh_lod – LOD mesh.

  • settings – the fbx export settings.

  • resources – HW resource configuration parameters.

  • logger – Logging callback.

  • progress – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

class pix4dvortex.io.fbx.Settings(self: pix4dvortex.io.fbx.Settings, *, lod_levels_to_export: collections.abc.Sequence[SupportsInt] = [], _y_up: bool = False, _meters_to_export_unit: SupportsFloat | None = None)
property lod_levels_to_export

Indices of the level of detail to export, zero being the lowest resolution level. Export all levels if empty. The valid LOD levels can be obtained using the export_levels_face_count function

GeoTIFF

GeoTIFF export tools

pix4dvortex.io.geotiff.to_cog(*args, **kwargs)

Overloaded function.

  1. to_cog(*, input_path: os.PathLike | str | bytes, output_path: os.PathLike | str | bytes, settings: collections.abc.Mapping[str, str] = {}) -> None

Convert a GeoTIFF file into a cloud optimized GeoTIFF (COG) file.

Parameters:

  • input_path – Path to the input geotiff file.

  • output_path – Path to the output COG file.

  • settings – Configuration parameters for the conversion. See the creation options of GDAL’s COG driver for details.

  1. to_cog(*, view: pix4dvortex.dmodel._GeotiffView, output_path: os.PathLike | str | bytes, settings: collections.abc.Mapping[str, str] = {}) -> None

Convert a GeoTIFF view into a cloud optimized GeoTIFF (COG) file.

Parameters:

  • view – a GeoTIFF view returned by any of gen_dsm, gen_ortho, gen_ortho_gmesh.

  • output_path – Path to the output COG file.

  • settings – Configuration parameters for the conversion. See the creation options of GDAL’s COG driver for details.

pix4dvortex.io.geotiff.write_geotiff(*, output_path: os.PathLike | str | bytes, tiles: None | pix4dvortex.dsm._DsmTiles | pix4dvortex.ortho._OrthoTiles, gsd: SupportsFloat | None = None, settings: pix4dvortex.io.geotiff.Settings = pix4dvortex.io.geotiff.Settings(), progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None) → None

Write raster tiles into a GeoTIFF file.

Parameters:

  • output_path – Path to the output file.

  • tiles – List of either DSM or orthomosaic raster tiles. The tiles must all have the same resolution.

  • gsd – [optional, deprecated] Ignored.

  • settings – Configuration parameters.

  • progress_callback – (optional) Callback function to report progress (step, percentage). Reports a single step named Writing DSM GeoTIFF or Writing orthomosaic GeoTIFF from 0 to 100, depending on the tile type.

Raises:

  • ValueError – if tiles is empty.

  • ValueError – if the resolution value of all tiles is not the same.

pix4dvortex.io.geotiff.write_geotiff_tile(*, output_path: os.PathLike | str | bytes, tile: pix4dvortex.dsm._Tile | pix4dvortex.ortho._Tile, gsd: SupportsFloat | None = None, settings: pix4dvortex.io.geotiff.Settings = pix4dvortex.io.geotiff.Settings()) → None

Write a raster tile into a GeoTIFF file.

Parameters:

  • output_path – Path to the output file.

  • tile – Raster tile.

  • gsd – [optional, deprecated] Ignored.

  • settings – Configuration parameters.

pix4dvortex.io.geotiff.write_geotiff_view(*, output_path: os.PathLike | str | bytes, view: pix4dvortex.dmodel._GeotiffView, link: bool = True, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None) → None

Write a GeoTIFF view into a file.

Parameters:

  • output_path – Path to the output file.

  • view – List of either DSM or orthomosaic raster tiles. The tiles must all have the same resolution.

  • link – (optional) If True, hard-link the source files instead of copying them if possible. If hard-linking is not possible a copy is used as a fallback. Defaults to True.

  • progress_callback – (optional) Callback function to report progress (step, percentage). Reports a single step named Writing GeoTIFF: [file name] from 0 to 100.

Raises:

ValueError – if the view doesn’t contain a GDAL dataset.

class pix4dvortex.io.geotiff.Settings(self: pix4dvortex.io.geotiff.Settings, *, compression: pix4dvortex.io.geotiff.Settings.Compression = Compression.LZW, xml_xmp: str = '', sw: str = '', no_data_value: SupportsFloat | None = None, extra: collections.abc.Mapping[str, str] = {})
property compression

The compression algorithm.

property extra

Additional configuration parameters for the serialization. See the creation options of GDAL’s GTIFF driver for details.

property no_data_value

Deprecated. Only used by write_geotiff and write_geotiff_tile when writing DSM/DTM tiles. Prefer setting the no data value in dsm.Settings at generation time.

property sw

Write the software used to write the GeoTIFF file into the TIFF metadata.

property xml_xmp

XML string with XMP data. It can be generated with ExifView.

class pix4dvortex.io.geotiff.Settings.Compression(self: pix4dvortex.io.geotiff.Settings.Compression, value: SupportsInt)
LZW = <Compression.LZW: 1>
NoCompression = <Compression.NoCompression: 0>

LAS

LAS export tools

pix4dvortex.io.las.write_pcl(*, output_path: os.PathLike | str | bytes, point_cloud: pix4dvortex.pcl.PointCloud, compress: bool = False, las_version: pix4dvortex.io.las.LasVersion = LasVersion.V1_2, _point_filter_factory: collections.abc.Callable[[pix4dvortex.pcl._View], collections.abc.Callable[[SupportsInt], bool]] = None, progress_callback: object = None) → None

Serialize a point cloud object to a LAS/LAZ file.

Serialize a point cloud object to a LAS/LAZ file. The format (LAS/LAZ) is determined from the file extension if it matches “.las” or “.laz” (case insensitive). Otherwise it is determined by the compress parameter.

Parameters:

  • output_path – The output file path. The format is inferred from the extension if matching “.las” or “.laz” as described above.

  • point_cloud – The point cloud object to serialize.

  • compress – Set output format to LAZ/LAS if True/False respectively. Has no effect if format can be inferred from output_path extension.

  • las_version – LAS version to use in serialization.

  • _point_filter_factory – Experimental mechanism to inject user-defined point filtering.

  • progress_callback – (optional) Callback function to report progress (step, percentage). Reports a single step named Writing LAS point cloud from 0 to 100.

Raises:
class pix4dvortex.io.las.LasVersion(self: pix4dvortex.io.las.LasVersion, value: SupportsInt)
V1_2 = <LasVersion.V1_2: 0>
V1_4 = <LasVersion.V1_4: 1>

OBJ

Utilities for exporting mesh data to OBJ format.

pix4dvortex.io.obj.version() → str
pix4dvortex.io.obj.write_mesh(output_path: os.PathLike | str | bytes, mesh_geom: pix4dvortex.mesh._MeshGeom, texture: pix4dvortex.mesh._Texture, settings: pix4dvortex.io.obj.Settings = pix4dvortex.io.obj.Settings()) → None

Write a triangular mesh into an OBJ file.

Parameters:

  • output_path – Path to the output file.

  • mesh_geom – Mesh geometry defined by a list of vertex coordinates (x,y,z) and a list of mesh faces.

  • texture – Mesh texture opaque data container.

  • settings – (optional) Configuration settings.

Raises:

  • RuntimeError – if the mesh data is invalid or inconsistent.

  • ValueError – if the texture file is invalid.

class pix4dvortex.io.obj.Settings(self: pix4dvortex.io.obj.Settings, *, texture_fmt: pix4dvortex.io.obj.Settings.TextureFmt = TextureFmt.JPEG, jpeg_quality: SupportsInt = 75)
property jpeg_quality

JPEG quality parameter. Ignored if texture_fmt is not JPEG.

property texture_fmt

Format of output texture file.

class pix4dvortex.io.obj.Settings.TextureFmt(self: pix4dvortex.io.obj.Settings.TextureFmt, value: SupportsInt)
JPEG = <TextureFmt.JPEG: 0>
PNG = <TextureFmt.PNG: 1>

PLY

Utilities for exporting Gaussian splatting data to PLY format.

pix4dvortex.io.ply.write_gsplat(*, output_path: os.PathLike | str | bytes, gsplat: pix4dvortex.gsplat.GaussianSplatting, max_sh_degree: SupportsInt = 3) → None

Write a Gaussian splatting model as a PLY file.

Parameters:

  • output_path – Path to the output file.

  • gsplat – Gaussian splatting model.

  • max_sh_degree – Maximum spherical harmonics color degree to export. Must be between 0 and 3. Exporting only up to a lower degree will result in a simpler color representation, reducing the file size but also the visual quality of the rendered model. Note that with max_sh_degree set to a value other than 0 or 3, not all renderers may be compatible with the PLY file.

SLPK

Utilities for exporting mesh data to SLPK format.

pix4dvortex.io.slpk.version() → str
pix4dvortex.io.slpk.write_mesh(*, output_path: os.PathLike | str | bytes, mesh_lod: pix4dvortex.mesh._MeshLOD, _geog_cs: pix4dvortex.coordsys.SpatialReference | None = None, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), logger: collections.abc.Callable[[SupportsInt, str], None] = None, progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → None

Write a triangular LOD mesh into an SLPK file.

Parameters:

  • output_path – Path to the output file.

  • mesh_lod – LOD mesh.

  • _geog_cs – (optional) Geographical coordinate system suitable for geolocating the mesh. Currently, only WGS84 is supported. If omitted, the original input projected spatial reference system (see pix4dvortex.cameras.ProjectedCameras()) is used.

  • resources – HW resource configuration parameters.

  • logger – Logging callback.

  • progress – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

pix4dvortex.io.slpk.write_pcl(*, output_path: os.PathLike | str | bytes, point_cloud: pix4dvortex.pcl.PointCloud, resources: pix4dvortex.proc.Resources = pix4dvortex.proc.Resources(), progress_callback: collections.abc.Callable[[str, SupportsInt], None] = None, stop_function: collections.abc.Callable[[], bool] = None) → None

Write a point cloud as an SLPK LOD file.

Parameters:

  • output_path – Path to the output file.

  • point_cloud – Point cloud.

  • resources – HW resource configuration parameters.

  • progress – (optional) Callback function to report progress (step, percentage).

  • stop_function – (optional) Callback function to request stopping; return True to stop processing.

OPF (experimental)

Experimental project utilities.

Warning

This module is currently experimental. Although breaking changes are not foreseen, they cannot be ruled out. The main functionality is expected to remain unchanged, and any breaking changes should be minor and easy to adapt to.

This module contains experimental OPF project utilities to simplify common OPF project related operations such as:

  • Storing pix4dvortex data model objects in an OPF project and writing them to disk.

  • Reading pix4dvortex data model objects from an OPF project on disk.

  • Bundling an entire OPF project from one location to another.

class pix4dvortex._project.ProjectWriter(*, id: str, name: str, description: str, root_dir: PathLike | None = None, logger: Callable[[int, str], None] | None = None)

Handle storing OPF compatible objects and saving them to files.

add_item(*, obj: CalibratedCameras | CalibratedIntersectionTiePoints | Calibration | CameraList | CameraOptimizationHints | Constraints | Features | GLTFGSplat | GLTFPointCloud | InputCameras | InputControlPoints | IntersectionTiePoints | Matches | OriginalMatches | ProjectedCameras | ProjectedControlPoints | SceneRefFrame | SegmentGraphs2D | _RadiometryInputs | _RadiometrySettings | _SurfaceModelMesh, source_ids: list[str] | None = None, labels: list[str] | None = None) → str

Store an OPF compatible data object as an OPF project item.

Note

This method is suited for storing objects that have no connection to other OPF items, such as pix4dvortex.dmodel.SceneRefFrame or pix4dvortex.dmodel.CameraList. For more complex objects, prefer storing the corresponding OPF item composite using add_item_composite() instead of using this one to manually load the connected objects and setting their sources.

Serializes an object compatible with an OPF item type into OPF format files and stores item in project. Ensures no duplicate objects are stored.

Parameters:

  • obj – a data object representing an OPF item.

  • source_ids – OPF items of sources. These must already be stored in the project.

  • labels – Optional labels to add to stored OPF project item.

Returns:

Unique id of stored item.

add_item_composite(*, obj: InputCameras | ProjectedCameras | _CalibratedScene | PointCloud | GaussianSplatting, labels: list[str] | None = None, source_ids: list[str] | None = None) → str

Store a composite of multiple OPF compatible objects as OPF project items.

Serializes an object containing multiple OPF compatible sub-object into OPF format files and stores items in project. Sets required item sources. Internally calls add_item() to consistently store the individual OPF items without duplication.

Parameters:

  • obj – a data object representing a composite of OPF items. Supported types are InputCameras, ProjectedCameras, _CalibratedScene, PointCloud, and GaussianSplatting (when the gsplat extension is installed). For Gaussian splatting, scene_reference_frame is always attached; input_cameras and calibration are attached when a unique item of that type is already stored in the project (Matic-aligned / OPF extension sources).

  • labels – Optional labels to add to stored OPF top project item.

Returns:

Unique id of stored top OPF item.

Raises:

ValueError – if obj is not a supported OPF item composite.

close(*, filename: PathLike = 'project.opf') → Path

Write all stored objects to files and return the path of the project file.

class pix4dvortex._project.ProjectReader(project_path: PathLike, logger: Callable[[int, str], None] | None = None)

Handle loading OPF compatible objects from files.

load_obj(opf_class: type[CalibratedCameras | CalibratedIntersectionTiePoints | Calibration | CameraList | CameraOptimizationHints | Constraints | Features | GLTFGSplat | GLTFPointCloud | InputCameras | InputControlPoints | IntersectionTiePoints | Matches | OriginalMatches | ProjectedCameras | ProjectedControlPoints | SceneRefFrame | SegmentGraphs2D | _RadiometryInputs | _RadiometrySettings | _SurfaceModelMesh] | type[InputCameras | ProjectedCameras | _CalibratedScene | PointCloud | GaussianSplatting], label_pred: Callable[[list[str]], bool] | None = None) → CalibratedCameras | CalibratedIntersectionTiePoints | Calibration | CameraList | CameraOptimizationHints | Constraints | Features | GLTFGSplat | GLTFPointCloud | InputCameras | InputControlPoints | IntersectionTiePoints | Matches | OriginalMatches | ProjectedCameras | ProjectedControlPoints | SceneRefFrame | SegmentGraphs2D | _RadiometryInputs | _RadiometrySettings | _SurfaceModelMesh | InputCameras | ProjectedCameras | _CalibratedScene | PointCloud | GaussianSplatting

Load a data object of a given class.

This method loads either a single OPF item type from dmodel (or pcl / gsplat), or a pix4dvortex composite type that aggregates multiple connected OPF items.

Note

For standalone OPF items with no item dependencies, such as pix4dvortex.dmodel.SceneRefFrame or pix4dvortex.dmodel.CameraList, pass the corresponding dmodel class directly. For higher-level objects that span multiple OPF items, pass a composite type such as pix4dvortex.cameras.InputCameras, pix4dvortex.cameras.ProjectedCameras, pix4dvortex.calib._CalibratedScene, pix4dvortex.pcl.PointCloud or pix4dvortex.gsplat.GaussianSplatting (if available). Composite loading resolves item sources and reconstructs the object graph automatically, similar to how ProjectWriter.add_item_composite() stores connected objects.

Parameters:

  • opf_class – the class of the object to be loaded.

  • label_pred – A predicate taking a list of OPF item labels to narrow search of OPF item types.

If opf_class is an OPF item type, the first object with a positive predicate call will be selected. Ignored if opf_class is a pix4dvortex composite type.

Returns:

An object of type opf_class. If opf_class is an OPF item type and labels is set, one or more matching labels are required.

Raises:

  • ValueError – if opf_class is not an OPF item or composite item.

  • LookupError – if no items of the right class found.

  • RuntimeError – if more than one object matching object is found.

pix4dvortex._project.package_project(*, project_path: PathLike, dst_dir: PathLike) → Path

Move all project files to a common root directory and fix image paths.

Moves all files defined by a project file, including images, into a single directory such that they can be packaged and transferred to an external host. Takes care of setting all internal URIs as URI references, with paths relative the location of the top level project file.

Parameters:

  • project_path – path of project file of project to be packaged.

  • dst_dir – destination directory to which project files and images are written.

Returns:

The path of the new top level project file.

Utilities

General utilities

Generic utility collection.

pix4dvortex.util.collect_hw_info()

Collect HW info.

pix4dvortex.util.collect_stats(*, msg_handler=None, task_specific=None)

Collect usage stats and pass them to a message handler.

pix4dvortex.util.hash_id(filename)

Calculate hash-based identifier of arbitrarily large file.

The identifier is a 64 bit big integer built from a BLAKE2b hash of the file contents. The most significant byte corresponds to the beginning of the sequence of hash bytes.

pix4dvortex.util.hw_info()

Return a dict with host hardware info.

pix4dvortex.util.path_to_url(path)

Return a file URI from a file path.

pix4dvortex.util.sha256(filename)

Calculate SHA(2)256 of arbitrarily large file.

pix4dvortex.util.task_info(task)

Task function information.

pix4dvortex.util.timestamp(filename)

File modification UTC date-time string in ISO 8601 format.

pix4dvortex.util.url_to_path(url)

Extract the path from a URL.

Processing utilities

exception pix4dvortex.proc.StopProcessing
class pix4dvortex.proc.Resources(self: pix4dvortex.proc.Resources, *, max_ram: SupportsInt = 8589934592, max_threads: SupportsInt = 0, use_gpu: bool = False, max_gpu_mem: SupportsInt = 4294967296, work_dir: os.PathLike | str | bytes = PosixPath('/tmp'))
to_dict(self: pix4dvortex.proc.Resources) → dict

Return a dictionary representation of the resources.

property max_gpu_mem

Maximum GPU memory in bytes.

property max_ram

Maximum RAM available for processing in bytes. 0 is an invalid value.

property max_threads

Maximum number of threads to use for processing. 0 means use the number of logical cores.

property use_gpu
property work_dir

Temporary work space. It will be created if it doesn’t exist. Defaults to system temporary directory.

Geometry

Module for geometric utilities.

class pix4dvortex.geom.Box
max_corner(self: pix4dvortex.geom.Box) → list
min_corner(self: pix4dvortex.geom.Box) → list
class pix4dvortex.geom.Polygon2D(self: pix4dvortex.geom.Polygon2D, *, outer_ring: collections.abc.Sequence[Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(2)']], inner_rings: collections.abc.Sequence[collections.abc.Sequence[Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(2)']]] = [])

Two-dimensional polygon.

A two-dimensional polygon is defined by an outer ring, and an optional set of non-overlapping inner rings. A point is within the polygon if it is inside the outer ring and outside the inner rings.

Initialize a Polygon2D from an outer ring and an optional set of inner rings.

Rings have no self-intersections and are non-overlapping.

Parameters:

  • outer_ring – an iterable of points defining the outer ring.

  • inner_rings – (optional) an iterable of iterables of points defining the inner rings of the polygon.

Raises:

RuntimeError – if any of the rings is overlapping or self-intersecting.

is_within(self: pix4dvortex.geom.Polygon2D, point: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(2)']) → bool
class pix4dvortex.geom.Roi2D(*args, **kwargs)

Two-dimensional region of interest (ROI).

A 2D ROI is defined as a set of Polygon2D objects. A point is within the ROI if it is within any of the polygons that define it.

Overloaded function.

  1. __init__(self: pix4dvortex.geom.Roi2D, *, polygon: pix4dvortex.geom.Polygon2D) -> None

Initialize a Roi2D from a Polygon2D.

  1. __init__(self: pix4dvortex.geom.Roi2D, *, polygons: collections.abc.Sequence[pix4dvortex.geom.Polygon2D]) -> None

Initialize a Roi2D from a set of Polygon2Ds.

Parameters:

polygons – an iterable of non-overlapping polygons.

Raises:

RuntimeError – if any of the polygons is overlapping.

is_within(self: pix4dvortex.geom.Roi2D, point: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(2)']) → bool
class pix4dvortex.geom.Roi3D(self: pix4dvortex.geom.Roi3D, *, polygon: pix4dvortex.geom.Polygon2D, min_z: SupportsFloat | None = None, max_z: SupportsFloat | None = None)

Three-dimensional region of interest (ROI).

A 3D ROI is defined by the outer ring of a 2D polygon and min/max Z bounds. A point is within the ROI if it is within the 2D polygon and between the Z bounds. Inner rings are not supported and will be ignored.

Initialize a Roi3D from a Polygon2D and Z bounds.

Parameters:

  • polygon – a Polygon2D defining the XY boundary.

  • min_z – minimum Z coordinate.

  • max_z – maximum Z coordinate.

is_within(self: pix4dvortex.geom.Roi3D, point: Annotated[collections.abc.Sequence[SupportsFloat], 'FixedSize(3)']) → bool

Check if a 3D point is within this ROI.

Parameters:

point – a 3D point as a sequence of 3 numbers [x, y, z].

Returns:

True if the point is within the ROI, False otherwise.

pix4dvortex.geom.make_roi(*args, **kwargs)

Overloaded function.

  1. make_roi(centers: collections.abc.Sequence[typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[2, 1]”]]) -> pix4dvortex.geom.Roi2D

Compute an automatic region of interest from camera center positions.

Creates a 2D multi-polygon ROI that covers all given camera centers using an automatic surface coverage algorithm based on Delaunay triangulation with alpha-shapes.

Parameters:

centers – Camera center positions in 2D as a sequence of [x, y] points.

Returns:

A Roi2D representing the automatic ROI.

Raises:

RuntimeError – if fewer than 3 points are provided or the alpha-shape algorithm fails.

  1. make_roi(centers: collections.abc.Sequence[typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[2, 1]”]], alpha: typing.SupportsFloat, offset: typing.SupportsFloat) -> pix4dvortex.geom.Roi2D

Compute an automatic region of interest with custom alpha and offset parameters.

Creates a 2D multi-polygon ROI with fine-grained control over the surface coverage algorithm.

Parameters:

  • centers – Camera center positions in 2D as a sequence of [x, y] points.

  • alpha – Alpha parameter for the alpha-shape algorithm (controls boundary tightness).

  • offset – Offset parameter for expanding the coverage area.

Returns:

A Roi2D representing the automatic ROI.

Raises:

RuntimeError – if fewer than 3 points are provided or the alpha-shape algorithm fails.

Spatial reference systems

class pix4dvortex.coordsys.BaseToCanonCnv(self: pix4dvortex.coordsys.BaseToCanonCnv, *, base_to_canonical: pix4dvortex.dmodel.BaseToCanonical)

A converter to transform from the base to the translated canonical SRS.

convert(*args, **kwargs)

Overloaded function.

  1. convert(self: pix4dvortex.coordsys.BaseToCanonCnv, point: typing.Annotated[collections.abc.Sequence[typing.SupportsFloat], “FixedSize(2)”], *, apply_offset: bool = True) -> list

  2. convert(self: pix4dvortex.coordsys.BaseToCanonCnv, point: typing.Annotated[collections.abc.Sequence[typing.SupportsFloat], “FixedSize(3)”], *, apply_offset: bool = True) -> list

convert_inplace(self: pix4dvortex.coordsys.BaseToCanonCnv, arg0: pix4dvortex.geom.Roi2D) → None
class pix4dvortex.coordsys.CanonToBaseCnv(self: pix4dvortex.coordsys.CanonToBaseCnv, *, base_to_canonical: pix4dvortex.dmodel.BaseToCanonical)

A converter to transform from the translated canonical to the base SRS.

convert(*args, **kwargs)

Overloaded function.

  1. convert(self: pix4dvortex.coordsys.CanonToBaseCnv, point: typing.Annotated[collections.abc.Sequence[typing.SupportsFloat], “FixedSize(2)”], *, apply_offset: bool = True) -> list

  2. convert(self: pix4dvortex.coordsys.CanonToBaseCnv, point: typing.Annotated[collections.abc.Sequence[typing.SupportsFloat], “FixedSize(3)”], *, apply_offset: bool = True) -> list

convert_inplace(self: pix4dvortex.coordsys.CanonToBaseCnv, arg0: pix4dvortex.geom.Roi2D) → None
class pix4dvortex.coordsys.CoordinateConverter(self: pix4dvortex.coordsys.CoordinateConverter, *, src: pix4dvortex.coordsys.SpatialReference, dst: pix4dvortex.coordsys.SpatialReference, src_geoid_height: SupportsFloat | None = None, dst_geoid_height: SupportsFloat | None = None)

Construct a coordinate converter based on two spatial reference systems with optional geoid heights. If geoid height is provided for a SRS, it supersedes any vertical transformation specific for the vertical component of the SRS in question. Conversions between different ellipsoids are still applied on the vertical axes. It’s important to note that a 0 height is not the same thing as a null height.

Parameters:

  • src – Source SRS (SRS to start from).

  • dst – Destination SRS (SRS to go to).

  • src_geoid_height – (optional) Single geoid undulation value (aka geoid_height), to be provided when src (source SRS) has no geoid.

  • dst_geoid_height – (optional) Single geoid undulation value (aka geoid_height), to be provided when dst (destination SRS) has no geoid.

Raises:

  • RuntimeError – if this transformation is not supported.

  • RuntimeError – If a geoid height is given for a spatial reference system which is not compound or has a defined geoid model name or a bad SRS is given.

  • RuntimeError – If either src (source SRS) or dst (destination SRS) contains or is an engineering spatial reference system.

convert(*args, **kwargs)

Overloaded function.

  1. convert(self: pix4dvortex.coordsys.CoordinateConverter, arg0: typing.Annotated[collections.abc.Sequence[typing.SupportsFloat], “FixedSize(3)”]) -> list

  2. convert(self: pix4dvortex.coordsys.CoordinateConverter, arg0: typing.SupportsFloat, arg1: typing.SupportsFloat, arg2: typing.SupportsFloat) -> tuple[float, float, float]

class pix4dvortex.coordsys.SpatialReference(*args, **kwargs)

Overloaded function.

  1. __init__(self: pix4dvortex.coordsys.SpatialReference, wkt: str) -> None

Create a SpatialReference object from a WKT string.

  1. __init__(self: pix4dvortex.coordsys.SpatialReference, *, horizontal_wkt: str, vertical_wkt: str, geoid: str | None = None) -> None

Create a SpatialReference object from horizontal and vertical WKT strings.

Parameters:

  • horizontal_wkt – Horizontal WKT string.

  • vertical_wkt – Vertical WKT string.

  • geoid – (optional) A valid geoid model corresponding to the given vertical SRS. If omitted, an unspecified geoid (if more than one is available for the vertical SRS) is used as default.

Raises:

ValueError – if the geoid model is invalid.

class Axis
property conversion_factor
property name
property unit_name
as_horizontal(self: pix4dvortex.coordsys.SpatialReference) → pix4dvortex.coordsys.SpatialReference

Create a projected spatial reference from the horizontal component of this one.

Returns:

A new horizontal spatial reference derived from this one.

Raises:

  • RuntimeError – if SRS does not have a horizontal component.

  • RuntimeError – if SRS is engineering and not 2-dimensional.

as_utm(self: pix4dvortex.coordsys.SpatialReference, *, lat: SupportsFloat, lon: SupportsFloat) → pix4dvortex.coordsys.SpatialReference

Create a UTM spatial reference from this one originating at the coordinates.

Parameters:

  • lat – Latitude of the origin (in degrees).

  • lon – Longitude of the origin (in degrees).

Returns:

A new UTM spatial reference derived from this one, centered on the given latitude and longitude.

Raises:

RuntimeError – if this SRS is not geographic.

as_vertical(self: pix4dvortex.coordsys.SpatialReference) → pix4dvortex.coordsys.SpatialReference

Create a spatial reference from this one.

Returns:

A new vertical spatial reference derived from this one.

Raises:

RuntimeError – if SRS is not vertical or has a vertical component.

as_wkt(self: pix4dvortex.coordsys.SpatialReference, *, wkt_convention: pix4dvortex.coordsys.WktConvention = WktConvention.WKT2_2019) → str

Return the WKT representation of this spatial reference.

Parameters:

wkt_convention – (optional) The WKT convention to use, defaults to WKT2.

Returns:

A WKT string representation of this spatial reference.

Raises:

RuntimeError – a WKT cannot be produced in the requested convention.

axes(self: pix4dvortex.coordsys.SpatialReference) → list[pix4dvortex.coordsys.SpatialReference.Axis]

Axes of this spatial reference.

Returns:

Array of Axis objects corresponding to the axes of this spatial reference system. The array may be of length 1, 2 or 3 depending on the dimensions of the SRS (vertical, horizontal or compound respectively).

axes_3d(self: pix4dvortex.coordsys.SpatialReference) → Annotated[list[pix4dvortex.coordsys.SpatialReference.Axis], 'FixedSize(3)']

3D axes of this spatial reference.

Returns:

Length 3 array of Axis objects corresponding to the axes of this spatial reference system. If the SRS is 3-dimensional, returns the same as axes(). If the SRS is 2-dimensional, the 3rd component is assumed to be an ellipsoidal height.

Raises:

  • RuntimeError – if SRS is vertical and not compound.

  • RuntimeError – if SRS is 2-dimensional and projected, and non-isometric.

geoid(self: pix4dvortex.coordsys.SpatialReference) → str

The geoid model used by this spatial reference, or an empty string in case of the default geoid model.

identifier(self: pix4dvortex.coordsys.SpatialReference) → str
is_compound(self: pix4dvortex.coordsys.SpatialReference) → bool
is_engineering(self: pix4dvortex.coordsys.SpatialReference) → bool
is_geographic(self: pix4dvortex.coordsys.SpatialReference) → bool
is_isometric(self: pix4dvortex.coordsys.SpatialReference) → bool
is_left_handed(self: pix4dvortex.coordsys.SpatialReference) → bool
is_projected(self: pix4dvortex.coordsys.SpatialReference) → bool
is_vertical(self: pix4dvortex.coordsys.SpatialReference) → bool
name(self: pix4dvortex.coordsys.SpatialReference) → str
pix4dvortex.coordsys.get_scene_ref_frame(*args, **kwargs)

Overloaded function.

  1. get_scene_ref_frame(*, definition: str, shift: typing.Annotated[collections.abc.Sequence[typing.SupportsFloat], “FixedSize(3)”] = [0.0, 0.0, 0.0], geoid_height: typing.SupportsFloat | None = None) -> pix4dvortex.dmodel.SceneRefFrame

Creates a SceneRefFrame object from a WKT string and optional shift & geoid_height values.

Returns:

A SceneRefFrame object.

Parameters:

  • definition – WKT string

  • shift – (optional) An internal vector used to shift coordinates to center the SRS to the scene.

  • geoid_height – (optional) Single geoid undulation value (aka geoid_height), to be provided when proj SRS has no geoid.

Raises:

  • RuntimeError – if SRS is vertical and not compound.

  • RuntimeError – if SRS is 2-dimensional and projected, and non-isometric.

  1. get_scene_ref_frame(*, proj_srs: pix4dvortex.coordsys.SpatialReference, shift: typing.Annotated[collections.abc.Sequence[typing.SupportsFloat], “FixedSize(3)”] = [0.0, 0.0, 0.0], geoid_height: typing.SupportsFloat | None = None) -> pix4dvortex.dmodel.SceneRefFrame

Creates a SceneRefFrame object from a SpatialReference object and optional shift & geoid_height values.

Returns:

A SceneRefFrame object.

Parameters:

  • proj_srs – A SpatialReference object.

  • shift – (optional) An internal vector used to shift coordinates to center the SRS to the scene.

  • geoid_height – (optional) Single geoid undulation value (aka geoid_height), to be provided when proj SRS has no geoid.

Raises:

  • RuntimeError – if SRS is vertical and not compound.

  • RuntimeError – if SRS is 2-dimensional and projected, and non-isometric.

pix4dvortex.coordsys.srs_from_code(*args, **kwargs)

Overloaded function.

  1. srs_from_code(code: str) -> pix4dvortex.coordsys.SpatialReference

Create a SpatialReference object from an authority code string.

Parameters:

code – A valid authority code string (e.g. “EPSG:2056”).

  1. srs_from_code(*, horizontal_code: str, vertical_code: str, geoid: str | None = None) -> pix4dvortex.coordsys.SpatialReference

Create a SpatialReference object from horizontal and vertical authority code strings.

Parameters:

  • horizontal_code – A valid horizontal SRS authority code string (e.g. “EPSG:4326”).

  • vertical_code – A valid vertical SRS authority code string (e.g. “EPSG:5773”).

  • geoid – (optional) A valid geoid model corresponding to the given vertical SRS (e.g. EGM96). If omitted, an unspecified geoid (if more than one is available for the vertical SRS) is used as default.

Raises:

ValueError – if the geoid model is invalid.

pix4dvortex.coordsys.srs_from_epsg(*args, **kwargs)

Overloaded function.

  1. srs_from_epsg(epsg: typing.SupportsInt) -> pix4dvortex.coordsys.SpatialReference

Create a SpatialReference object from an EPSG authority code.

Parameters:

epsg – A valid EPSG code (e.g. 2056).

  1. srs_from_epsg(*, horizontal_epsg: typing.SupportsInt, vertical_epsg: typing.SupportsInt, geoid: str | None = None) -> pix4dvortex.coordsys.SpatialReference

Create a SpatialReference object from horizontal and vertical EPSG authority codes.

Parameters:

  • horizontal_epsg – A valid horizontal SRS EPSG code (e.g. 4326).

  • vertical_epsg – A valid vertical SRS EPSG code (e.g. 5773).

  • geoid – (optional) A valid geoid model corresponding to the given vertical SRS (e.g. EGM96). If omitted, an unspecified geoid (if more than one is available for the vertical SRS) is used as default.

Raises:

ValueError – if the geoid model is invalid.

pix4dvortex.coordsys.version() → str

Version of the Pix4D SRS API.

pix4dvortex.coordsys.wkt_from_code(code: str, *, wkt_convention: pix4dvortex.coordsys.WktConvention = WktConvention.WKT2_2019, wkt_options: pix4dvortex.coordsys.WktExportOptions = WktExportOptions.DEFAULT) → str

Create a WKT string from an authority code string.

Parameters:

  • code – A valid authority code string (e.g. “EPSG:2056”).

  • wkt_convention – (optional) Specifies WKT1 or WKT2 convention.

  • wkt_options – (optional) Bit mask specifying additional options.

pix4dvortex.coordsys.wkt_from_epsg(epsg_no: SupportsInt, *, wkt_convention: pix4dvortex.coordsys.WktConvention = WktConvention.WKT2_2019, wkt_options: pix4dvortex.coordsys.WktExportOptions = WktExportOptions.DEFAULT) → str

Create a WKT string from an EPSG authority code.

Parameters:

  • epsg_no – A valid EPSG code (e.g. 2056).

  • wkt_convention – (optional) Specifies WKT1 or WKT2 convention.

  • wkt_options – (optional) Bit mask specifying additional options.

class pix4dvortex.coordsys.WktExportOptions(self: pix4dvortex.coordsys.WktExportOptions, value: SupportsInt)
DEFAULT = <WktExportOptions.DEFAULT: 0>
MULTILINE = <WktExportOptions.MULTILINE: 1>
class pix4dvortex.coordsys.WktConvention(self: pix4dvortex.coordsys.WktConvention, value: SupportsInt)
WKT1_GDAL = <WktConvention.WKT1_GDAL: 0>
WKT2_2019 = <WktConvention.WKT2_2019: 1>

Calibration IO

IO utilites for calibration results.

pix4dvortex.calib.io.unpack_camera_params(camera)

Unpack calibrated camera parameters into a dict.