xrprimer.data_structure

camera

class xrprimer.data_structure.camera.BaseCameraParameter(*args: Any, **kwargs: Any)

LoadFile(filename: str) → bool

Load camera name and parameters from a dumped json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

bool – True if load succeed.

SaveFile(filename: str) → int

Dump camera name and parameters to a json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

int – returns 0.

clone() → xrprimer.data_structure.camera.camera.BaseCameraParameter

Clone a new CameraPrameter instance like self.

Returns

BaseCameraParameter

dump(filename: str) → None

Dump camera name and parameters to a json file.

Parameters

filename (str) – Path to the dumped json file.

Raises

RuntimeError – Fail to dump a json file.

classmethod fromfile(filename: str) → xrprimer.data_structure.camera.camera.BaseCameraParameter

Construct a camera parameter data structure from a json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

CameraParameter – An instance of CameraParameter class.

get_extrinsic_r() → list

Get extrinsic rotation matrix.

Returns

list – Nested list of float32, 3x3 R mat.

get_extrinsic_t() → list

Get extrinsic translation vector.

Returns

list – Nested list of float32, T vec of length 3.

get_intrinsic(k_dim: int = 3) → list

Get intrinsic K matrix.

Parameters

k_dim (int, optional) – If 3, returns a 3x3 mat. Else if 4, returns a 4x4 mat. Defaults to 3.

Raises

ValueError – k_dim is neither 3 nor 4.

Returns

list – Nested list of float32, 4x4 or 3x3 K mat.

intrinsic33() → numpy.ndarray

Get an intrinsic matrix in shape (3, 3).

Returns

ndarray – An ndarray of intrinsic matrix.

inverse_extrinsic() → None

Inverse the direction of extrinsics, between world to camera and camera to world.

load(filename: str) → None

Load camera name and parameters from a dumped json file.

Parameters

filename (str) – Path to the dumped json file.

Raises

• FileNotFoundError – File not found at filename.

• ValueError – Content in filename is not correct.

set_KRT(K: Optional[Union[list, numpy.ndarray]] = None, R: Optional[Union[list, numpy.ndarray]] = None, T: Optional[Union[list, numpy.ndarray]] = None, world2cam: Optional[bool] = None) → None

Set K, R to matrix and T to vector.

Parameters

• K (Union[list, np.ndarray, None]) – Nested list of float32, 4x4 or 3x3 K mat. Defaults to None, intrisic will not be changed.

• R (Union[list, np.ndarray, None]) – Nested list of float32, 3x3 R mat. Defaults to None, extrisic_r will not be changed.

• T (Union[list, np.ndarray, None]) – List of float32, T vector. Defaults to None, extrisic_t will not be changed.

• world2cam (Union[bool, None], optional) – Whether the R, T transform points from world space to camera space. Defaults to None, self.world2cam will not be changed.

set_intrinsic(mat3x3: Optional[Union[list, numpy.ndarray]] = None, width: Optional[int] = None, height: Optional[int] = None, fx: Optional[float] = None, fy: Optional[float] = None, cx: Optional[float] = None, cy: Optional[float] = None, perspective: bool = True) → None

Set the intrinsic of a camera. Note that mat3x3 has a higher priority than fx, fy, cx, cy.

Parameters

• mat3x3 (list, optional) – A nested list of intrinsic matrix, in shape (3, 3). If mat is given, fx, fy, cx, cy will be ignored. Defaults to None.

• width (int) – Width of the screen.

• height (int) – Height of the screen.

• fx (float, optional) – Focal length. Defaults to None.

• fy (float, optional) – Focal length. Defaults to None.

• cx (float, optional) – Camera principal point. Defaults to None.

• cy (float, optional) – Camera principal point. Defaults to None.

• perspective (bool, optional) – Whether it is a perspective camera, if not, it’s orthographics. Defaults to True.

set_resolution(height: int, width: int) → None

Set resolution of the camera.

Parameters

• height (int) – Height of the screen.

• width (int) – Width of the screen.

class xrprimer.data_structure.camera.FisheyeCameraParameter(*args: Any, **kwargs: Any)

LoadFile(filename: str) → bool

Load camera name and parameters from a dumped json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

bool – True if load succeed.

SaveFile(filename: str) → bool

Dump camera name and parameters to a json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

bool – True if save succeed.

clone() → xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter

Clone a new CameraPrameter instance like self.

Returns

FisheyeCameraParameter

get_dist_coeff() → list

Get distortion coefficients in self.convention.

Raises

NotImplementedError – convention not supported.

Returns

• list – A list of distortion coefficients, in a

• turn defined by self.convention.

set_dist_coeff(dist_coeff_k: list, dist_coeff_p: list) → None

Set distortion coefficients from list.

Parameters

• dist_coeff_k (list) – List of float. [k1, k2, k3, k4, k5, k6]. When length of list is n and n<6, only the first n coefficients will be set.

• dist_coeff_p (list) – List of float. [p1, p2]. To set only p1, pass [p1].

class xrprimer.data_structure.camera.OmniCameraParameter(*args: Any, **kwargs: Any)

LoadFile(filename: str) → bool

Load camera name and parameters from a dumped json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

bool – True if load succeed.

SaveFile(filename: str) → bool

Dump camera name and parameters to a json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

bool – True if save succeed.

clone() → xrprimer.data_structure.camera.omni_camera.OmniCameraParameter

Clone a new CameraPrameter instance like self.

Returns

PinholeCameraParameter

set_dist_coeff(dist_coeff_k: list, dist_coeff_p: list) → None

Set distortion coefficients from list.

Parameters

• dist_coeff_k (list) – List of float. [k1, k2, k3, k4, k5, k6]. When length of list is n and n<6, only the first n coefficients will be set.

• dist_coeff_p (list) – List of float. [p1, p2]. To set only p1, pass [p1].

set_omni_param(xi: Optional[float] = None, D: Optional[list] = None) → None

Set omni parameters.

Parameters

• xi (Union[float, None], optional) – Omni parameter xi. Defaults to None, xi will not be modified.

• D (Union[list, None], optional) – List of float. [D0, D1, D2, D3]. When length of list is n and n<4, only the first n parameters will be set. Defaults to None, D will not be modified.

class xrprimer.data_structure.camera.PinholeCameraParameter(*args: Any, **kwargs: Any)

LoadFile(filename: str) → bool

Load camera name and parameters from a dumped json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

bool – True if load succeed.

SaveFile(filename: str) → bool

Dump camera name and parameters to a json file.

Parameters

filename (str) – Path to the dumped json file.

Returns

bool – True if save succeed.

clone() → xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter

Clone a new CameraParameter instance like self.

Returns

PinholeCameraParameter

xrprimer.calibration

class xrprimer.calibration.BaseCalibrator(work_dir: str = './temp', logger: Union[None, str, logging.Logger] = None)

Base class of camera calibrator.

calibrate() → xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter

Calibrate a camera or several cameras. Input args shall not be modified and the calibrated camera will be returned.

Returns

PinholeCameraParameter – The calibrated camera.

class xrprimer.calibration.MviewFisheyeCalibrator(chessboard_width: int, chessboard_height: int, chessboard_square_size: int, work_dir: str, calibrate_intrinsic: bool = False, calibrate_distortion: bool = False, calibrate_extrinsic: bool = True, logger: Union[None, str, logging.Logger] = None)

Multi-view extrinsic calibrator for distorted fisheye cameras.

calibrate(frames: List[List[str]], fisheye_param_list: List[xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter]) → List[xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter]

Calibrate multi-FisheyeCameraParameters with a chessboard. It takes intrinsics and distortion coefficients from fisheye_param_list, calibrates only extrinsics on undistorted frames.

Parameters

• frames (List[List[str]]) – A nested list of distorted image paths. The shape is [n_frame, n_view], and each element is the path to an image file. ‘’ stands for an empty image.

• fisheye_param_list (List[FisheyeCameraParameter]) – A list of FisheyeCameraParameters. Intrinsic matrix and distortion coefficients are necessary for calibration.

Returns

List[FisheyeCameraParameter] – A list of calibrated fisheye cameras, name, logger, resolution will be kept.

class xrprimer.calibration.MviewPinholeCalibrator(chessboard_width: int, chessboard_height: int, chessboard_square_size: int, calibrate_intrinsic: bool = False, calibrate_extrinsic: bool = True, logger: Union[None, str, logging.Logger] = None)

Multi-view extrinsic calibrator for pinhole cameras.

calibrate(frames: List[List[str]], pinhole_param_list: List[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter]) → List[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter]

Calibrate multi-PinholeCameraParameters with a chessboard.

Parameters

• frames (List[List[str]]) – A nested list of image paths. The shape is [n_frame, n_view], and each element is the path to an image file. ‘’ stands for an empty image.

• pinhole_param_list (List[PinholeCameraParameter]) – A list of PinholeCameraParameters. Intrinsic matrix is necessary for calibration.

Returns

List[PinholeCameraParameter] – A list of calibrated pinhole cameras, name, logger, resolution will be kept.

class xrprimer.calibration.SviewFisheyeDistortionCalibrator(chessboard_width: int, chessboard_height: int, logger: Union[None, str, logging.Logger] = None)

Single-view distortion calibrator for distorted fisheye camera.

It takes an init intrinsic, fix it and calibrate distortion coefficients.

calibrate(frames: List[str], fisheye_param: xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter) → xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter

Calibrate FisheyeCameraParameter with a chessboard. It takes intrinsics from fisheye_param, calibrates only distortion coefficients on undistorted frames.

Parameters

• frames (List[str]) – A list of distorted image paths.

• fisheye_param (FisheyeCameraParameter) – An instance of FisheyeCameraParameter. Intrinsic matrix is necessary for calibration, and the input instance will not be modified.

Returns

FisheyeCameraParameter – An instance of FisheyeCameraParameter. Distortion coefficients are the only difference from input.

xrprimer.ops

projection

class xrprimer.ops.projection.BaseProjector(camera_parameters: List[Union[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, str]], logger: Union[None, str, logging.Logger] = None)

BaseProjector for points projection.

project(points: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray

Project points with self.camera_parameters.

Parameters

• points (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points3d, in shape [n_point, 3].

• points_mask (Union[np.ndarray, list, tuple], optional) – An ndarray or a nested list of mask, in shape [n_point, 1]. If points_mask[index] == 1, points[index] is valid for projection, else it is ignored. Defaults to None.

Returns

np.ndarray – An ndarray of points2d, in shape [n_view, n_point, 2].

project_single_point(points: Union[numpy.ndarray, list, tuple]) → numpy.ndarray

Project a single point with self.camera_parameters.

Parameters

points (Union[np.ndarray, list, tuple]) – An ndarray or a list of points3d, in shape [3].

Returns

np.ndarray – An ndarray of points2d, in shape [n_view, 2].

set_cameras(camera_parameters: List[Union[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter]]) → None

Set cameras for this projector.

Parameters

camera_parameters (List[Union[PinholeCameraParameter, str]]) – A list of PinholeCameraParameter or FisheyeCameraParameter.

class xrprimer.ops.projection.OpencvProjector(camera_parameters: List[xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter], logger: Union[None, str, logging.Logger] = None)

Projector for points projection, powered by OpenCV.

project(points: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray

Project points with self.camera_parameters.

Parameters

• points (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points3d, in shape [n_point, 3].

• points_mask (Union[np.ndarray, list, tuple], optional) – An ndarray or a nested list of mask, in shape [n_point, 1]. If points_mask[index] == 1, points[index] is valid for projection, else it is ignored. Defaults to None.

Returns

np.ndarray – An ndarray of points2d, in shape [n_view, n_point, 2].

project_single_point(points: Union[numpy.ndarray, list, tuple]) → numpy.ndarray

Project a single point with self.camera_parameters.

Parameters

points (Union[np.ndarray, list, tuple]) – An ndarray or a list of points3d, in shape [3].

Returns

np.ndarray – An ndarray of points2d, in shape [n_view, 2].

triangulation

class xrprimer.ops.triangulation.BaseTriangulator(camera_parameters: List[Union[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, str]], logger: Union[None, str, logging.Logger] = None)

BaseTriangulator for points triangulation.

get_reprojection_error(points2d: Union[numpy.ndarray, list, tuple], points3d: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray

Get reprojection error between reprojected points2d and input points2d.

Parameters

• points2d (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points2d, in shape [n_view, n_point, 2].

• points3d (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points3d, in shape [n_point, 3].

• points_mask (Union[np.ndarray, list, tuple], optional) – An ndarray or a nested list of mask, in shape [n_view, n_point, 1]. If points_mask[index] == 1, points[index] is valid for triangulation, else it is ignored. If points_mask[index] == np.nan, the whole pair will be ignored and not counted by any method. Defaults to None.

Returns

np.ndarray – An ndarray in shape [n_view, n_point, 2], record offset alone x, y axis of each point2d.

set_cameras(camera_parameters: List[Union[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter]]) → None

Set cameras for this triangulator.

Parameters

camera_parameters (List[Union[PinholeCameraParameter, str]]) – A list of PinholeCameraParameter or FisheyeCameraParameter.

Raises

NotImplementedError – Some camera_parameter from camera_parameters has a different camera convention from class requirement.

triangulate(points: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray

Triangulate points with self.camera_parameters.

Parameters

• points (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points2d, in shape [n_view, n_point 2].

• points_mask (Union[np.ndarray, list, tuple], optional) – An ndarray or a nested list of mask, in shape [n_view, n_point 1]. If points_mask[index] == 1, points[index] is valid for triangulation, else it is ignored. If points_mask[index] == np.nan, the whole pair will be ignored and not counted by any method. Defaults to None.

Returns

np.ndarray – An ndarray of points3d, in shape [n_point, 3].

triangulate_single_point(points: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray

Triangulate a single point with self.camera_parameters.

Parameters

• points (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points2d, in shape [n_view, 2].

• points_mask (Union[np.ndarray, list, tuple], optional) – An ndarray or a nested list of mask, in shape [n_view, 1]. If points_mask[index] == 1, points[index] is valid for triangulation, else it is ignored. Defaults to None.

Returns

np.ndarray – An ndarray of points3d, in shape [3, ].

class xrprimer.ops.triangulation.OpencvTriangulator(camera_parameters: List[xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter], multiview_reduction: typing_extensions.Literal[mean, median] = 'mean', logger: Union[None, str, logging.Logger] = None)

Triangulator for points triangulation, powered by OpenCV.

get_reprojection_error(points2d: Union[numpy.ndarray, list, tuple], points3d: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray

Get reprojection error between reprojected points2d and input points2d.

Parameters

• points2d (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points2d, in shape [n_view, n_point, 2].

• points3d (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points3d, in shape [n_point, 3].

• points_mask (Union[np.ndarray, list, tuple], optional) – An ndarray or a nested list of mask, in shape [n_view, n_point, 1]. If points_mask[index] == 1, points[index] is valid for triangulation, else it is ignored. If points_mask[index] == np.nan, the whole pair will be ignored and not counted by any method. Defaults to None.

Returns

np.ndarray – An ndarray in shape [n_view, n_point, 2], record offset alone x, y axis of each point2d.

classmethod prepare_triangulation_mat(camera_parameters: List[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter]) → numpy.ndarray

Prepare projection matrix for triangulation. According to opencv,

ProjectionMatrix = [intrinsic33] * [extrinsic_r|extrinsic_t]

Parameters

camera_parameters (List[PinholeCameraParameter]) – A list of pinhole camera parameters.

Returns

np.ndarray – The projection matrix in shape [n_camera, 3, 4].

triangulate(points: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray

Triangulate points with self.camera_parameters.

Parameters

• points (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points2d, in shape [n_view, n_point 2].

• points_mask (Union[np.ndarray, list, tuple], optional) – An ndarray or a nested list of mask, in shape [n_view, n_point 1]. If points_mask[index] == 1, points[index] is valid for triangulation, else it is ignored. If points_mask[index] == np.nan, the whole pair will be ignored and not counted by any method. Defaults to None.

Returns

np.ndarray – An ndarray of points3d, in shape [n_point, 3].

triangulate_single_point(points: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray

Triangulate a single point with self.camera_parameters.

Parameters

• points (Union[np.ndarray, list, tuple]) – An ndarray or a nested list of points2d, in shape [n_view, 2].

• points_mask (Union[np.ndarray, list, tuple], optional) – An ndarray or a nested list of mask, in shape [n_view, 1]. If points_mask[index] == 1, points[index] is valid for triangulation, else it is ignored. Defaults to None.

Returns

np.ndarray – An ndarray of points3d, in shape [3, ].

xrprimer.transform

camera

xrprimer.transform.camera.rotate_camera(cam_param: Union[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter], rotation_mat: numpy.ndarray) → Union[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter]

Apply rotation to a camera parameter.

Parameters

• cam_param (Union[PinholeCameraParameter, FisheyeCameraParameter]) – The camera to rotate.

• rotation_mat (np.ndarray) – Rotation matrix defined in world space, shape [3, 3].

Returns

Union[PinholeCameraParameter, FisheyeCameraParameter] – Rotated camera in same type and extrinsic direction like the input camera.

xrprimer.transform.camera.translate_camera(cam_param: Union[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter], translation: numpy.ndarray) → Union[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter]

Apply the translation to a camera parameter.

Parameters

• cam_param (Union[PinholeCameraParameter, FisheyeCameraParameter]) – The camera to translate.

• translation (np.ndarray) – Translation vector defined in world space, shape [3,].

Returns

Union[PinholeCameraParameter, FisheyeCameraParameter] – Translated camera in same type and extrinsic direction like the input camera.

xrprimer.transform.camera.undistort_camera(distorted_cam: xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter) → xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter

Undistort a FisheyeCameraParameter to PinholeCameraParameter.

Parameters

distorted_cam (FisheyeCameraParameter) – An instance of FisheyeCameraParameter. Convention will be checked, resolution, intrinsic mat and distortion coefficients will be used.

Raises

NotImplementedError – Camera convention not supported.

Returns

PinholeCameraParameter – Undistorted camera parameter.

xrprimer.transform.camera.undistort_images(distorted_cam: xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter, image_array: numpy.ndarray) → Tuple[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, numpy.ndarray]

Undistort a FisheyeCameraParameter to PinholeCameraParameter, and undistort an array of images shot on a fisheye camera.

Parameters

• distorted_cam (FisheyeCameraParameter) – An instance of FisheyeCameraParameter. Convention will be checked, resolution, intrinsic mat and distortion coefficients will be used.

• image_array (np.ndarray) – An array of images, in shape [n_frame, height, width, n_channel].

Raises

NotImplementedError – Camera convention not supported.

Returns

Tuple[PinholeCameraParameter, np.ndarray] –

PinholeCameraParameter:

Undistorted camera parameter.

np.ndarray:

Corrected images in the same shape as input.

xrprimer.transform.camera.undistort_points(distorted_cam: xrprimer.data_structure.camera.fisheye_camera.FisheyeCameraParameter, points: numpy.ndarray) → Tuple[xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter, numpy.ndarray]

Undistort a FisheyeCameraParameter to PinholeCameraParameter, and undistort an array of points in fisheye camera screen. Parameters and points will be casted to np.float64 before operation.

Parameters

• distorted_cam (FisheyeCameraParameter) – An instance of FisheyeCameraParameter. Convention will be checked, resolution, intrinsic mat and distortion coefficients will be used.

• points (np.ndarray) – An array of points, in shape […, 2], int or float. … could be [n_point, ], [n_frame, n_point, ] [n_frame, n_object, n_point, ], etc.

Raises

NotImplementedError – Camera convention not supported.

Returns

Tuple[PinholeCameraParameter, np.ndarray] –

PinholeCameraParameter:

Undistorted camera parameter.

np.ndarray:

Corrected points location in the same shape as input, dtype is np.float64.

camera convention

xrprimer.transform.convention.camera.convert_camera_parameter(cam_param: xrprimer.data_structure.camera.camera.BaseCameraParameter, dst: str) → xrprimer.data_structure.camera.camera.BaseCameraParameter

Convert a camera parameter instance into opencv convention.

Parameters

• cam_param (BaseCameraParameter) – The input camera parameter, which is an instance of BaseCameraParameter subclass.

• dst (str) – The name of destination convention.

Returns

BaseCameraParameter – A camera in the same type as input, whose direction is same as cam_param, and convention equals to dst.

xrprimer.transform.convention.camera.downgrade_k_4x4(k: numpy.ndarray) → numpy.ndarray

Convert opencv 4x4 intrinsic matrix to 3x3.

Parameters

K (np.ndarray) – Input 4x4 intrinsic matrix, left mm defined.

Returns

np.ndarray – Output 3x3 intrinsic matrix, left mm defined.

[[fx, 0, px],

[0, fy, py], [0, 0, 1]]

xrprimer.transform.convention.camera.upgrade_k_3x3(k: numpy.ndarray, is_perspective: bool = True) → numpy.ndarray

Convert opencv 3x3 intrinsic matrix to 4x4.

Parameters

• K (np.ndarray) –

  Input 3x3 intrinsic matrix, left mm defined.

  [[fx, 0, px],

  [0, fy, py], [0, 0, 1]]

• is_perspective (bool, optional) – whether is perspective projection. Defaults to True.

Returns

np.ndarray – Output intrinsic matrix.

for perspective:

[[fx, 0, px, 0], [0, fy, py, 0], [0, 0, 0, 1], [0, 0, 1, 0]]

for orthographics:

[[fx, 0, 0, px], [0, fy, 0, py], [0, 0, 1, 0], [0, 0, 0, 1]]

image

xrprimer.transform.image.bgr2rgb(input_array: numpy.ndarray, color_dim: int = - 1) → numpy.ndarray

Convert image array of any shape between BGR and RGB.

Parameters

• input_array (np.ndarray) – An array of images. The shape could be: [h, w, n_ch], [n_frame, h, w, n_ch], [n_view, n_frame, h, w, n_ch], etc.

• color_dim (int, optional) – Which dim is the color channel. Defaults to -1.

Returns

np.ndarray

xrprimer.utils

class xrprimer.utils.Existence(value)

State of file existence.

xrprimer.utils.array_to_images(image_array: numpy.ndarray, output_folder: str, img_format: str = '%06d.png', resolution: Optional[Union[Tuple[int, int], Tuple[float, float]]] = None, disable_log: bool = False, logger: Union[None, str, logging.Logger] = None) → None

Convert an array to images directly.

Parameters

• image_array (np.ndarray) – shape should be (f * h * w * 3).

• output_folder (str) – output folder for the images.

• img_format (str, optional) – format of the images. Defaults to ‘%06d.png’.

• resolution (Optional[Union[Tuple[int, int], Tuple[float, float]]], optional) – (height, width) of the output images. Defaults to None.

• disable_log (bool, optional) – whether close the ffmepg command info. Defaults to False.

Raises

• FileNotFoundError – check output folder.

• TypeError – check input array.

Returns

None

xrprimer.utils.array_to_video(image_array: numpy.ndarray, output_path: str, fps: Union[int, float] = 30, resolution: Optional[Union[Tuple[int, int], Tuple[float, float]]] = None, disable_log: bool = False, logger: Union[None, str, logging.Logger] = None) → None

Convert an array to a video directly, gif not supported.

Parameters

• image_array (np.ndarray) – shape should be (f * h * w * 3).

• output_path (str) – output video file path.

• fps (Union[int, float, optional) – fps. Defaults to 30.

• resolution (Optional[Union[Tuple[int, int], Tuple[float, float]]], optional) – (height, width) of the output video. Defaults to None.

• disable_log (bool, optional) – whether close the ffmepg command info. Defaults to False.

Raises

• FileNotFoundError – check output path.

• TypeError – check input array.

Returns

None.

xrprimer.utils.check_path(input_path: str, allowed_suffix: List[str] = [], allowed_existence: List[xrprimer.utils.path_utils.Existence] = [<Existence.FileExist: 0>], path_type: typing_extensions.Literal[file, dir, auto] = 'auto', logger: Union[None, str, logging.Logger] = None) → None

Check both existence and suffix, raise error if check fails.

Parameters

• input_path (str) – Path to a file or folder.

• allowed_suffix (List[str], optional) – What extension names are allowed. Offer a list like [‘.jpg’, ‘.jpeg’]. When it’s [], all will be received. Use [‘’] then directory is allowed. Defaults to [].

• allowed_existence (List[Existence], optional) – What existence types are allowed. Defaults to [Existence.FileExist, ].

• path_type (Literal['file', 'dir', 'auto'], optional) – What kind of file do we expect at the path. Choose among file, dir, auto. Defaults to ‘auto’.. Defaults to ‘auto’.

• logger (Union[None, str, logging.Logger], optional) – Logger for logging. If None, root logger will be selected. Defaults to None.

Raises

• ValueError – Wrong file suffix.

• FileNotFoundError – Wrong file existence.

xrprimer.utils.check_path_existence(path_str: str, path_type: typing_extensions.Literal[file, dir, auto] = 'auto') → xrprimer.utils.path_utils.Existence

Check whether a file or a directory exists at the expected path.

Parameters

• path_str (str) – Path to check.

• path_type (Literal['file', 'dir', 'auto'], optional) – What kind of file do we expect at the path. Choose among file, dir, auto. Defaults to ‘auto’.

Raises

KeyError – if path_type conflicts with path_str

Returns

Existence –

0. FileExist: file at path_str exists.

1. DirectoryExistEmpty: folder at path exists and.

2. DirectoryExistNotEmpty: folder at path_str exists and not empty.

3. MissingParent: its parent doesn’t exist.

4. DirectoryNotExist: expect a folder at path_str, but not found.

5. FileNotExist: expect a file at path_str, but not found.

xrprimer.utils.check_path_suffix(path_str: str, allowed_suffix: Union[str, List[str]] = '') → bool

Check whether the suffix of the path is allowed.

Parameters

• path_str (str) – Path to check.

• allowed_suffix (List[str], optional) – What extension names are allowed. Offer a list like [‘.jpg’, ‘.jpeg’]. When it’s [], all will be received. Use [‘’] then directory is allowed. Defaults to ‘’.

Returns

bool – True: suffix test passed False: suffix test failed

xrprimer.utils.get_logger(logger: Union[None, str, logging.Logger] = None) → logging.Logger

Get logger.

Parameters

logger (Union[None, str, logging.Logger]) – None for root logger. Besides, pass name of the logger or the logger itself. Defaults to None.

Returns

logging.Logger

xrprimer.utils.images_to_array(input_folder: str, resolution: Optional[Union[Tuple[int, int], Tuple[float, float]]] = None, img_format: str = '%06d.png', start: int = 0, end: Optional[int] = None, remove_raw_files: bool = False, disable_log: bool = False, logger: Union[None, str, logging.Logger] = None) → numpy.ndarray

Read a folder of images as an array of (f * h * w * 3).

Parameters

• input_folder (str) – folder of input images.

• resolution (Union[Tuple[int, int], Tuple[float, float]]) – resolution(height, width) of output. Defaults to None.

• img_format (str, optional) – format of images to be read. Defaults to ‘%06d.png’.

• start (int, optional) – start frame index. Inclusive. If < 0, will be converted to frame_index range in [0, n_frame]. Defaults to 0.

• end (int, optional) – end frame index. Exclusive. Could be positive int or negative int or None. If None, all frames from start till the last frame are included. Defaults to None.

• remove_raw_files (bool, optional) – whether remove raw images. Defaults to False.

• disable_log (bool, optional) – whether close the ffmepg command info. Defaults to False.

Raises

FileNotFoundError – check the input path.

Returns

np.ndarray – shape will be (f * h * w * 3).

xrprimer.utils.images_to_array_opencv(input_folder: str, resolution: Optional[Union[Tuple[int, int], Tuple[float, float]]] = None, img_format: Optional[str] = None, start: int = 0, end: Optional[int] = None, logger: Union[None, str, logging.Logger] = None) → numpy.ndarray

Read a folder of images as an array of (f * h * w * 3).

Parameters

• input_folder (str) – folder of input images.

• resolution (Union[Tuple[int, int], Tuple[float, float]]) – resolution(height, width) of output. Defaults to None.

• img_format (str, optional) – Format of images to be read, ‘jpg’ or ‘png’. Defaults to None.

• start (int, optional) – start frame index. Inclusive. If < 0, will be converted to frame_index range in [0, n_frame]. Defaults to 0.

• end (int, optional) – end frame index. Exclusive. Could be positive int or negative int or None. If None, all frames from start till the last frame are included. Defaults to None.

• logger (Union[None, str, logging.Logger], optional) – Logger for logging. If None, root logger will be selected. Defaults to None.

Raises

FileNotFoundError – check the input path.

Returns

np.ndarray – shape will be (f * h * w * 3).

xrprimer.utils.images_to_sorted_images(input_folder, output_folder, img_format='%06d')

Copy and rename a folder of images into a new folder following the img_format.

Parameters

• input_folder (str) – input folder.

• output_folder (str) – output folder.

• img_format (str, optional) – image format name, do not need extension. Defaults to ‘%06d’.

Returns

str – image format of the rename images.

xrprimer.utils.pad_for_libx264(image_array: numpy.ndarray) → numpy.ndarray

Pad zeros if width or height of image_array is not divisible by 2. Otherwise you will get.

“[libx264 @ 0x1b1d560] width not divisible by 2 “

Parameters

image_array (np.ndarray) – Image or images load by cv2.imread(). Possible shapes: 1. [height, width] 2. [height, width, channels] 3. [images, height, width] 4. [images, height, width, channels]

Returns

np.ndarray – A image with both edges divisible by 2.

xrprimer.utils.prepare_output_path(output_path: str, tag: str = 'output file', allowed_suffix: List[str] = [], path_type: typing_extensions.Literal[file, dir, auto] = 'auto', overwrite: bool = True, logger: Union[None, str, logging.Logger] = None) → None

Check output folder or file.

Parameters

• output_path (str) – could be folder or file.

• allowed_suffix (List[str], optional) – Check the suffix of output_path. If folder, should be [] or [‘’]. If could both be folder or file, should be [suffixs…, ‘’]. Defaults to [].

• tag (str, optional) – The string tag to specify the output type. Defaults to ‘output file’.

• path_type (Literal[, optional) – Choose file for file and dir for folder. Choose auto if allowed to be both. Defaults to ‘auto’.

• overwrite (bool, optional) – Whether overwrite the existing file or folder. Defaults to True.

Raises

• FileNotFoundError – suffix does not match.

• FileExistsError – file or folder already exists and overwrite is False.

Returns

None

xrprimer.utils.setup_logger(logger_name: str = 'root', logger_level: int = 20, logger_path: Optional[str] = None, logger_format: Optional[str] = None) → logging.Logger

Set up a logger.

Parameters

• logger_name (str, optional) – Name of the logger. Defaults to ‘root’.

• logger_level (int, optional) – Set the logging level of this logger. Defaults to logging.INFO.

• logger_path (str, optional) – Path to the log file. Defaults to None, no file will be written, StreamHandler will be used.

• logger_format (str, optional) – The formatter for logger handler. Defaults to None.

Returns

logging.Logger – A logger with settings above.

xrprimer.utils.video_to_array(input_path: str, resolution: Optional[Union[Tuple[int, int], Tuple[float, float]]] = None, start: int = 0, end: Optional[int] = None, disable_log: bool = False, logger: Union[None, str, logging.Logger] = None) → numpy.ndarray

Read a video/gif as an array of (f * h * w * 3).

Parameters

• input_path (str) – input path.

• resolution (Union[Tuple[int, int], Tuple[float, float]], optional) – resolution(height, width) of output. Defaults to None.

• start (int, optional) – start frame index. Inclusive. If < 0, will be converted to frame_index range in [0, n_frame]. Defaults to 0.

• end (int, optional) – end frame index. Exclusive. Could be positive int or negative int or None. If None, all frames from start till the last frame are included. Defaults to None.

• disable_log (bool, optional) – whether close the ffmepg command info. Defaults to False.

• logger (Union[None, str, logging.Logger], optional) – Logger for logging. If None, root logger will be selected. Defaults to None.

Raises

FileNotFoundError – check the input path.

Returns

np.ndarray – shape will be (f * h * w * 3).