xrprimer.data_structure¶
camera¶
- class xrprimer.data_structure.camera.BaseCameraParameter(*args: Any, **kwargs: Any)[source]¶
- LoadFile(filename: str) → bool[source]¶
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[source]¶
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[source]¶
Clone a new CameraPrameter instance like self.
- Returns
BaseCameraParameter
- dump(filename: str) → None[source]¶
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[source]¶
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[source]¶
Get extrinsic rotation matrix.
- Returns
list – Nested list of float32, 3x3 R mat.
- get_extrinsic_t() → list[source]¶
Get extrinsic translation vector.
- Returns
list – Nested list of float32, T vec of length 3.
- get_intrinsic(k_dim: int = 3) → list[source]¶
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[source]¶
Get an intrinsic matrix in shape (3, 3).
- Returns
ndarray – An ndarray of intrinsic matrix.
- inverse_extrinsic() → None[source]¶
Inverse the direction of extrinsics, between world to camera and camera to world.
- load(filename: str) → None[source]¶
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[source]¶
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[source]¶
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.
- class xrprimer.data_structure.camera.FisheyeCameraParameter(*args: Any, **kwargs: Any)[source]¶
- LoadFile(filename: str) → bool[source]¶
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[source]¶
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[source]¶
Clone a new CameraPrameter instance like self.
- Returns
FisheyeCameraParameter
- get_dist_coeff() → list[source]¶
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[source]¶
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)[source]¶
- LoadFile(filename: str) → bool[source]¶
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[source]¶
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[source]¶
Clone a new CameraPrameter instance like self.
- Returns
PinholeCameraParameter
- set_dist_coeff(dist_coeff_k: list, dist_coeff_p: list) → None[source]¶
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[source]¶
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)[source]¶
- LoadFile(filename: str) → bool[source]¶
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[source]¶
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[source]¶
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)[source]¶
Base class of camera calibrator.
- calibrate() → xrprimer.data_structure.camera.pinhole_camera.PinholeCameraParameter[source]¶
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)[source]¶
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][source]¶
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)[source]¶
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][source]¶
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)[source]¶
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[source]¶
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)[source]¶
BaseProjector for points projection.
- project(points: Union[numpy.ndarray, list, tuple], points_mask: Optional[Union[numpy.ndarray, list, tuple]] = None) → numpy.ndarray[source]¶
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[source]¶
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[source]¶
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)[source]¶
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[source]¶
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[source]¶
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)[source]¶
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[source]¶
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[source]¶
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[source]¶
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[source]¶
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)[source]¶
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[source]¶
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[source]¶
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[source]¶
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[source]¶
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][source]¶
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][source]¶
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[source]¶
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][source]¶
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][source]¶
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[source]¶
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[source]¶
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[source]¶
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[source]¶
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¶
- 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[source]¶
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[source]¶
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[source]¶
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[source]¶
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 –
FileExist: file at path_str exists.
DirectoryExistEmpty: folder at path exists and.
DirectoryExistNotEmpty: folder at path_str exists and not empty.
MissingParent: its parent doesn’t exist.
DirectoryNotExist: expect a folder at path_str, but not found.
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[source]¶
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[source]¶
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[source]¶
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[source]¶
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')[source]¶
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[source]¶
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[source]¶
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[source]¶
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[source]¶
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).