pyfisheye package

Subpackages

• pyfisheye.internal package
  • Subpackages
    • pyfisheye.internal.optimisation package
      • Submodules
      • pyfisheye.internal.optimisation.linear module
      • pyfisheye.internal.optimisation.nonlinear module
      • pyfisheye.internal.optimisation.optim_result module
      • Module contents
    • pyfisheye.internal.utils package
      • Submodules
      • pyfisheye.internal.utils.check_shapes module
      • pyfisheye.internal.utils.common module
      • Module contents
  • Submodules
  • pyfisheye.internal.projection module
    • backproject()
    • project()
    • project_fast()
  • Module contents
• pyfisheye.scripts package
  • Submodules
  • pyfisheye.scripts.calibrate module
    • Arguments
      • Arguments.distortion_centre_search_grid_size
      • Arguments.images
      • Arguments.initial_distortion_centre_x
      • Arguments.initial_distortion_centre_y
      • Arguments.log_level
      • Arguments.nonlinear_refinement
      • Arguments.num_monotonicity_constraint_samples
      • Arguments.optimise_distortion_centre
      • Arguments.pattern_num_cols
      • Arguments.pattern_num_rows
      • Arguments.pattern_tile_height
      • Arguments.pattern_tile_width
      • Arguments.save_calibration_to
      • Arguments.save_corner_det
      • Arguments.save_results
      • Arguments.show_corner_det
      • Arguments.show_results
      • Arguments.weighted_least_squares_threshold
    • calibrate()
  • pyfisheye.scripts.demo module
    • demo()
    • print_disclaimer()
    • run_calibration()
    • select_dataset()
    • unzip_images()
  • Module contents

Submodules

pyfisheye.calibration module

pyfisheye.calibration.calibrate(pattern_observations, image_height, image_width, pattern_num_rows, pattern_num_cols, pattern_width_x, pattern_width_y=None, calibration_options=CalibrationOptions(initial_distortion_centre_x=None, initial_distortion_centre_y=None, optimise_distortion_centre=True, distortion_centre_search_grid_size=20, distortion_centre_search_progress_bar=True, nonlinear_refinement=True, robust_wnls_threshold=1.0, monotonicity_constraint_samples=500))

Return type:

CalibrationResult

pyfisheye.calibration_options module

class pyfisheye.calibration_options.CalibrationOptions(initial_distortion_centre_x=None, initial_distortion_centre_y=None, optimise_distortion_centre=True, distortion_centre_search_grid_size=20, distortion_centre_search_progress_bar=True, nonlinear_refinement=True, robust_wnls_threshold=1.0, monotonicity_constraint_samples=500)

Bases: object

Parameters for the camera calibration procedure.

Parameters:

• initial_distortion_centre_x (Optional[float]) – Specify an initial distortion centre to use for nonlinear optimisation. Leave as None to use half of the image dimensions. optimise_distortion_centre is True, this value will be added to the search grid and the normal search procedure is carried out.

• initial_distortion_centre_y (Optional[float]) – Similar to initial_distortion_centr_x but on the vertical dimension.

• optimise_distortion_centre (bool) – If True perform a grid search - trying out many different distortion centres - to find the best distortion centre to use in the camera model. This is the slowest part of the algorithm.

• distortion_centre_search_grid_size (int) – Set the number of rows and columns in the 2D search grid used in the distortion centre search. Use 10-30 for a quick calibration and 100+ for a more accurate but slower (5+ minutes) calibration.

• distortion_centre_search_progress_bar (bool) – If True, use tqdm to display a progress bar in the terminal for the distortion centre search.

• nonlinear_refinement (bool) – If True, use the LM algorithm to perform a nonlinear refinement of the calibration parameters. This is recommended and takes a few seconds.

• robust_wnls_threshold (float) – The threshold to use for weighted nonlinear least squares. This controls robustness to misdetected corners in the calibration pattern. See Improved Wide-Angle, Fisheye and Omnidirectional Camera Calibration et al.

• monotonicity_constraint_samples (int) – The number of samples used to enforce a strictly decreasing camera model polynomial during the linear optimisation. Increasing this number can significantly impact the calibration time.

distortion_centre_search_grid_size: int = 20

distortion_centre_search_progress_bar: bool = True

initial_distortion_centre_x: Optional[float] = None

initial_distortion_centre_y: Optional[float] = None

monotonicity_constraint_samples: int = 500

nonlinear_refinement: bool = True

optimise_distortion_centre: bool = True

robust_wnls_threshold: float = 1.0

pyfisheye.calibration_result module

class pyfisheye.calibration_result.CalibrationResult(extrinsics, intrinsics, optimal_distortion_centre, stretch_matrix)

Bases: object

extrinsics: ndarray

intrinsics: ndarray

optimal_distortion_centre: ndarray

stretch_matrix: ndarray

pyfisheye.camera module

class pyfisheye.camera.Camera(distortion_centre, intrinsics, stretch_matrix=array([[1., 0.], [0., 1.]]), image_size_wh=None, precompute_lookup_table=False)

Bases: object

Stores the calibration parameters for a camera and provides methods for projection,

backprojection and more.

cam2world(pixels, normalise=True)

Backproject pixel(s) in the image to a ray in 3D space.

Parameters:

• pixels (ndarray) – The array of pixels, can be any shape as long as the last dimension is of length 2.

• normalise (bool) – If True, all returned rays will lie on the unit sphere.

Return type:

ndarray

Returns:

3D rays eminating from the camera in the camera’s coordinate system.

static from_json(path, **kwargs)

Instantiate a camera from a json file.

Parameters:

**kwargs – Optional overrides passed to __init__.

Return type:

Camera

Returns:

The instantiated camera.

map_perspective(points_or_pixels, img_width=None, img_height=None, rotation=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]))

Returns the map fed to cv2.remap in Camera.reproject_perspective().

Parameters:

• points_or_pixels (ndarray) – 2D points in the image or 3D points/rays in the camera coordinate system. Any shape as long as the last dimension equals 2 or 3.

• img_width (Optional[int]) – Number of pixels in the x-axis for the perspective projection. Leave as None and provide a height to automatically set this and maintain the aspect ratio.

• img_height (Optional[int]) – Number of pixels in the y-axis for the perspective projection. Leave as None and provide a width to automatically set this and maintain the aspect ratio.

• rotation (ndarray) – The rotation matrix to apply to the imaginary perspective camera prior to reprojection. Defaults to the identity so that no rotation is applied. For example, the extrinsic orientation of the camera (camera -> world) can be provided to correct for skewed/rotated perspective projections.

Return type:

ndarray

Returns:

A max of size (height, width, 2) specifying the coordinates in the original for each pixel in the destination image. Uses the provided points_or_pixels to compute the correct perspective camera parameters such that all points lie in the final image.

reproject_perspective(original_image, points_or_pixels, rotation=array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]]), img_width=None, img_height=None)

Reproject a region of a fisheye image to a perspective one.

Parameters:

• original_image (ndarray) – The original image to sample from. cv2.remap will be used to generate the perspective image with linear interpolation.

• points_or_pixels (ndarray) – 2D points in the image or 3D points/rays in the camera coordinate system. Any shape as long as the last dimension equals 2 or 3. The reprojected image will contain each point and surrounding pixels. It is sufficient to provide a bounding box or a small set of pixels of interest rather than a dense selection.

• rotation (ndarray) – The rotation matrix to apply to the imaginary perspective camera prior to reprojection. Defaults to the identity so that no rotation is applied. For example, the extrinsic orientation of the camera (camera -> world) can be provided to correct for skewed/rotated perspective projections.

• img_width (Optional[int]) – Number of pixels in the x-axis for the perspective projection. Leave as None and provide a height to automatically set this and keep the correct aspect ratio.

• img_height (Optional[int]) – Number of pixels in the y-axis for the perspective projection. Leave as None and provide a width to automatically set this and keep the correct aspect ratio.

Return type:

ndarray

Returns:

A max of size (height, width, 2) specifying the coordinates in the original for each pixel in the destination image.

to_json(path)

Export the calibration parameters to a json file.

Parameters:

path (str) – The path to write to.

Return type:

None

world2cam(points)

Project 3D points/rays in the camera coordinate system onto the image plane. This method

requires a polynomial inversion (i.e. eigenvalue decomposition) for each provided point.

Parameters:

points (ndarray) – An array with any number of dimensions as long as the last dimension has length 3.

Return type:

ndarray

Returns:

Pixel coordinates for each point. NaN is returned for failed projections.

world2cam_fast(points)

Project 3D points / rays in the camera coordinate system onto the image plane. This method

uses a lookup table and linear interpolation to compute the projection. The lookup table will be computed if it was not precomputed when instantiating the camera.

Parameters:

points (ndarray) – An array with any number of dimensions as long as the last dimension has length 3.

Return type:

ndarray

Returns:

Pixel coordinates for each point. NaN is returned for failed projections.

Module contents