carnivalmirror package

Submodules

carnivalmirror.calibration module

Definition of the Calibration object

class carnivalmirror.calibration.Calibration(K, D, width, height)

Bases: object

The Calibration object represents a set of intrinsic and distortion parameters and enables basic computation on them.

Variables:
  • n_fx (float) – Normalized fx intrinsic camera parameter (for height 1 pixel).
  • n_fy (float) – Normalized fy intrinsic camera parameter (for height 1 pixel).
  • n_cx (float) – Normalized cx intrinsic camera parameter (for height 1 pixel).
  • n_cy (float) – Normalized cy intrinsic camera parameter (for height 1 pixel).
  • k1 (float) – The k1 radial distortion parameter.
  • k2 (float) – The k2 radial distortion parameter.
  • k3 (float) – The k3 radial distortion parameter.
  • p1 (float) – The p1 tangential distortion parameter.
  • p2 (float) – The p2 tangential distortion parameter.
  • aspect_ratio (float) – The calibration aspect ratio.
__init__(K, D, width, height)

Initializes a Calibration object.

Initializes a calibration object from a set of intrinsic parameters and distortion coefficients.

Parameters:
  • K – A list with the camera matrix values ordered as [fx, fy, cx, cy] or a 3x3 array representing a camera matrix
  • D – A list of distortion coefficients ordered as [k1, k2, p1, p2, k3], all 5 coefficients should be provided
  • width (int) – Width of the image resolution at which the camera matrix was obtained
  • height (int) – Height of the image resolution at which the camera matrix was obtained
Raises:

TypeError – If any of the inputs do not match the expected types or dimensions.
appd(reference, width, height, interpolation=<sphinx.ext.autodoc.importer._MockObject object>, min_cropped_size=None, return_diff_map=False, map_width=None, map_height=None, normalized=False)

Calculate the Average Pixel Position Difference.

Parameters:
  • reference (Calibration) – Another Calibration object relative to which the metric will be computed
  • width (int) – Desired width for the rectified image, a base for calculating the metric
  • height (int) – Desired height for the rectified image, a base for calculating the metric
  • interpolation – cv2 interpolation method
  • quiet (bool) – If True, won’t show a warning if the aspect ratio of the image is not the same as the one of the calibration given during the initialization
  • strict (bool) – If True, will raise a ValueError exception if there is aspect ratio mismatch
  • min_cropped_size (tuple of int) – Passed to undistortion_maps_preserving
  • return_diff_map (bool) – If True, returns the difference map
  • map_width (int) – Width for the undistortion map, if None, `width`is used. Use the same aspect ratio for the maps as for the rectified image
  • map_height (int) – Height for the undistortion map, if None, height is used. Use the same aspect ratio for the maps as for the rectified image
  • normalized (bool) – If True, normalizes by the map diagonal
Returns:

a float or a tuple containing:

appd (float): The Average Pixel Position Difference between this calibration and the reference, calculated for the provided resolution.

diff_map (numpy array): If return_diff_map is True also returns the difference map
Return type:

tuple
Raises:
  • ValueError – See information about the strict parameter
  • RuntimeError – See information for undistortion_maps_preserving
delete_maps()

Deletes the stored maps in order to reduce the memory footprint of the object.

get_D()

Provides the distortion coefficents.

Returns:A list of the 5 distortion coefficients [k1, k2, p1, p2, k3]
Return type:numpy array
get_K(height=1)

Calculates the camera matrix for a particular resolution.

Calculates the camera matrix for an image with height (in pixels) as supplied, and width equal to self.aspect_ratio*height.

Parameters:height (int) – An interger representing the desired height (in pixels) for the camera matrix
Returns:A 3x3 camera matrix for the desired resolution
Return type:numpy array
rectify(image, interpolation=<sphinx.ext.autodoc.importer._MockObject object>, quiet=False, strict=False, result_width=None, result_height=None, mode='standard', min_cropped_size=None)

Rectify an image.

Parameters:
  • image (numpy array) – The input image. Should be cv2-compatible. Should be [width, height, channels]
  • interpolation – cv2 interpolation method
  • quiet (bool) – If True, won’t show a warning if the aspect ratio of the image is not the same as the one of the calibration given during the initialization
  • strict (bool) – If True, will raise a ValueError exception if there is aspect ratio mismatch
  • result_width (int) – Desired width for the rectified image, if None will use the input height
  • result_height (int) – Desired height for the rectified image, if None will use the input height
  • mode (str) – Can be standard or preserving, chooses between standard undistortion (with undistortion_maps) and undistortion with cropped and rescaled vaild aspect-ratio-preserving region (with undistortion_maps_preserving).
  • min_cropped_size (tuple of int) – Passed to undistortion_maps_preserving if mode is set to preserving
Returns:

The resulting image after rectification
Return type:

numpy array
Raises:

ValueError – See information about the strict parameter. Also raised if only one of map_width and map_height is None
undistortion_maps(width, height, map_width=None, map_height=None, interpolation=<sphinx.ext.autodoc.importer._MockObject object>)

Calculates the undistortion maps.

Based on OpenCV’s solution: https://docs.opencv.org/2.4/doc/tutorials/calib3d/camera_calibration/camera_calibration.html

Parameters:
  • width (int) – Desired width for the input image
  • height (int) – Desired height for the input image
  • map_width (int) – Desired width for the undistortion maps, default None and will use the input width
  • map_height (int) – Desired height for the undistortion maps, default None and will use the input height
  • interpolation – cv2 interpolation method, default is cv2.INTER_LANCZOS4
Returns:

The undistortion maps for the x-axis and y-axis
Return type:

(numpy array, numpy array)
Raises:

ValueError – If only one of map_width and map_height is None
undistortion_maps_preserving(width, height, min_cropped_size=None, map_width=None, map_height=None, interpolation=<sphinx.ext.autodoc.importer._MockObject object>)

Calculates the preserving undistortion maps.

Calculates an undistorion map that crops only the part of the undistorted image that has no missing pixels due to the rectification and that is the same aspect ratio as the provided size. Then it resizes it up to the original size.

Parameters:
  • width (int) – The desired width for the input image
  • height (int) – The desired height for the input image
  • min_cropped_size (int) – Optional, if provided as a (width, height) tuple, will raise RuntimeError if the cropped image is smaller than this
  • map_width (int) – The desired width for the undistortion maps, if None will use the input width
  • map_height (int) – The desired height for the undistortion maps, if None will use the input height
  • interpolation – cv2 interpolation method
Returns:

The preserving undistortion maps for the x-axis and y-axis
Return type:

(numpy array, numpy array)
Raises:
  • RuntimeError – If the region of validity is only zeros, if the cropped image is smaller than min_cropped_size, or if the aspect ratio cannot be preserved
  • ValueError – If only one of map_width and map_height is None

carnivalmirror.sampling module

Definition of the various Sampler objects

class carnivalmirror.sampling.ParallelBufferedSampler(sampler, n_jobs=4, buffer_size=16, cache_size=0)

Bases: carnivalmirror.sampling.Sampler

ParallelBufferedSampler paralelizes and buffers a given sampler.

Creates several background treads that sample Calibration objects and maintain a buffer of a specified size.

In order to stop the threads (and gracefully exit the parent process) you have to use the stop() method.

__init__(sampler, n_jobs=4, buffer_size=16, cache_size=0)

Given an initialized sampler, abstracts its parallelization and buffering.

Parameters:
  • sampler (Sampler) – A Sampler object to parallelize
  • n_jobs (int) – Number of threads to create
  • buffer_size (int) – Number of calibrations to keep in the buffer
  • cache_size (int) – Number of objects to keep in a cache in order to all fast sampling.
next()

Provide the next Calibration from the buffer.

Returns:A Calibration object
Return type:Calibration
stop()

Stops the background processes that fill the buffer.

class carnivalmirror.sampling.ParameterSampler(ranges, cal_width, cal_height)

Bases: carnivalmirror.sampling.Sampler

ParameterSampler provides uniform independent sampling within specified ranges of calibration parameters.

Variables:
  • width (int) – The width of the image(s) for which the calibrations are
  • height (int) – The height of the image(s) for which the calibrations are
  • aspect_ratio (float) – The calibration aspect ratio.
  • ranges (dict) – The provided sampling ranges for the calibration parameters
__init__(ranges, cal_width, cal_height)

Initializes a ParameterSampler object

Parameters:
  • ranges (dict) – A dictionary with keys [fx, fy, cx, cy, k1, k2, p1, p2, k3] and elements tuples describing the sampling range for each parameter. All intrinsic parameters must be provided. Missing distortion parameters will be sampled as 0. Parameters can be kept constant if both limits are the same.
  • cal_width (int) – The width of the image(s) for which the calibrations are
  • cal_height (int) – The height of the image(s) for which the calibrations are
Raises:

ValueError – If one of [fx, fy, cx, cy] is missing from ranges
next()

Generator method providing a randomly sampled Calibration

Returns:A Calibration object
Return type:Calibration
class carnivalmirror.sampling.Sampler(cal_width, cal_height)

Bases: object

Base Sampler class

Variables:
  • cal_width (int) – The width of the image(s) for which the calibrations are
  • cal_height (int) – The height of the image(s) for which the calibrations are
  • aspect_ratio (float) – The calibration aspect ratio.
__init__(cal_width, cal_height)

Initializes a Sampler object

Parameters:
  • cal_width (int) – The width of the image(s) for which the calibrations are
  • cal_height (int) – The height of the image(s) for which the calibrations are
histogram(reference, n_samples=1000, n_bins=10, return_values=False, **kwargs)

Obtains a histogram of APPD values

Samples n_samples times from the ranges of the parameters, calculates their APPD values with respect to a reference Calibration and builds a histogram from them.

Parameters:
  • reference (Calibration) – A reference Calibration object
  • n_samples (int) – Number of samples
  • n_bins (int) – Number of histogram bins
  • return_values (bool) – If True, will also return the sampled APPD values
  • **kwargs – Arguments to be passed to the appd method of Calibration (width and height required)
Returns:

a float or a tuple containing:

hist (numpy array): The values of the histogram (number of occurrences)

bin_edges (numpy array): The bin edges (length(hist)+1)

appd_values (list of float): The sampled values (only if return_values is set to True)
Return type:

tuple
next()

Should be implemented by children classes

class carnivalmirror.sampling.TriangularParameterSampler(ranges, reference, cal_width, cal_height)

Bases: carnivalmirror.sampling.Sampler

ParameterSampler provides uniform independent sampling within specified ranges of calibration parameters.

Variables:
  • width (int) – The width of the image(s) for which the calibrations are
  • height (int) – The height of the image(s) for which the calibrations are
  • aspect_ratio (float) – The calibration aspect ratio.
  • ranges (dict) – The provided sampling ranges for the calibration parameters
__init__(ranges, reference, cal_width, cal_height)

Initializes a ParameterSampler object

Parameters:
  • ranges (dict) – A dictionary with keys [fx, fy, cx, cy, k1, k2, p1, p2, k3] and elements tuples describing the sampling range for each parameter. All intrinsic parameters must be provided. Missing distortion parameters will be sampled as 0. Parameters can be kept constant if both limits are the same.
  • reference (Calibration) – A reference object that will be used to determine the mode of the triangular distribution for each axis
  • cal_width (int) – The width of the image(s) for which the calibrations are
  • cal_height (int) – The height of the image(s) for which the calibrations are
Raises:

ValueError – If one of [fx, fy, cx, cy] is missing from ranges
next()

Generator method providing a randomly sampled Calibration

Returns:A Calibration object
Return type:Calibration
class carnivalmirror.sampling.UniformAPPDSampler(ranges, cal_width, cal_height, reference, temperature=1, appd_range_dicovery_samples=1000, appd_range_bins=10, init_jobs=1, sampler='uniform', **kwargs)

Bases: carnivalmirror.sampling.Sampler

UniformAPPDSampler provides parameter sampling that results in approximately uniform APPD distribution

Variables:
  • width (int) – The width of the image(s) for which the calibrations are
  • height (int) – The height of the image(s) for which the calibrations are
  • aspect_ratio (float) – The calibration aspect ratio.
  • ranges (dict) – The provided sampling ranges for the calibration parameters
  • temperature (float) – Temperature used for Gibbs acceptance sampling
  • reference (Calibration) – The reference Calibration
  • bin_edges (list of float) – Marks the bin edges
  • bin_counts (list of int) – Stores how many samples were generated from each bin so far
__init__(ranges, cal_width, cal_height, reference, temperature=1, appd_range_dicovery_samples=1000, appd_range_bins=10, init_jobs=1, sampler='uniform', **kwargs)

Initializes a UniformAPPDSampler object

Parameters:
  • ranges (dict) – A dictionary with keys [fx, fy, cx, cy, k1, k2, p1, p2, k3] and elements tuples describing the sampling range for each parameter. All intrinsic parameters must be provided. Missing distortion parameters will be sampled as 0. Parameters can be kept constant if both limits are the same.
  • cal_width (int) – The width of the image(s) for which the calibrations are
  • cal_height (int) – The height of the image(s) for which the calibrations are
  • reference (Calibration) – A reference Calibration object
  • temperature (float) – Temperature used for Gibbs acceptance sampling
  • appd_range_dicovery_samples (int) – Number of samples obtained in order to find the range of achievable APPD values
  • appd_range_bins (int) – Number of histogram bins
  • init_jobs (int) – Number of jobs used for the initialization sampling
  • sampler (Sampler) – A type of sampler to use, ‘uniform’ or ‘triangular’
  • **kwargs – Arguments to be passed to the appd method of Calibration (width and height required, optionally map_width, map_height, interpolation)
Raises:
  • ValueError – If one of [fx, fy, cx, cy] is missing from ranges
  • RuntimeException – If a histogram bin with zero elements is encountered.
next()

Generator method providing a randomly sampled Calibration that results in a nearly uniform APPD distribution

Samples are taken uniformly but are accepted with probability -diff_with_smallest_bin/temperture.

Returns:A Calibration object
Return type:Calibration

Module contents