upsp.cam_cal_utils.internal_calibration

alpha_shape_is_safe(pts, alpha)

Returns an alpha shape generated from points and the alpha parameter

Returns an alpha shape constructed from the points and the given alpha parameters. An alpha shape is similar to a convex hull, but sets a maximum on the distance between two vertices. The distances is 1 / alpha. An alpha shape is a convex hull if the alpha parameter is 0.

The shape may be more accurately referred to as an alpha complex (rather than alpha shape) since it has poligonal edges, but many sources use alpha shape to refer to both.

Parameters

• pts (numpy.ndarray, shape (n, k) of floats) – Calibration points to create the alpha shape from. n is the number of points k is the dimensionality of the points (2 for image points, 3 for real world points)

• alpha (float) – Alpha parameter of the alpha shape. Larger means more points are rejected. Must be non-negative. Negative values are clipped to 0.

Returns

is_safe – Function that accepts an array-like object (list, np.array, etc) of points and returns a list of booleans of the same length. return[i] corresponds to point[i] and True means that point is inside the alpha shape (False means it is not).

Return type

callable

get_safe_pts(rmat, tvec, cameraMatrix, distCoeffs, obj_pts, cal_area_is_safe, cal_vol_is_safe, critical_pt=None)

Determines which obj_pts are inside the well behaved region of the internal calibration

Performs 3 checks on each of the obj_pts. The first check and second check is that each obj_pt and its projection are within the safe volume and safe area as defined by cal_area_is_safe and cal_vol_is_safe. These checks are always performed. The third check is not always necessary, and is more involved.

If the highest order (non-zero) radial distortion term of distCoeffs is negative, then at some real world distance from the camera optical axis, increasing the real world distance from the camera optical axis will decrease pixel distance of that point’s projection. I.e. moving farther out of frame will move the point closer to the image center. This is not a bug, but is not an accurate model of the physical system. This means that some object points very far out of the field of view can be projected into the frame. These points have a ‘negative derivative’ of the projection curve. As the input (real world distance from camera optical axis) increases, the output (projected distance from the image center) decreases.

The points need not be outside the field of view to have a negative derivative. So a simple FOV check is unfortunately insufficient. The third check is unnecessary if cal_area_is_safe and cal_vol_is_safe are well constructed. If they are not well constructed, the third check ensures the object points are in the well-behaved region of the internal calibration. For most cases, this means the object points are in the positive region of the internal calibration.

Parameters

• rmat (numpy.ndarray, shape (3, 3), float) – Rotation matrix from camera to object

• tvec (np.ndarray (3, 1), float) – Translation vector from camera to object

• cameraMatrix (numpy.ndarray, shape (3, 3), float) – The (openCV formatted) camera matrix for the camera

• distCoeffs (numpy.ndarray, shape (5, 1) or (5,), float) – The (openCV formatted) distortion coefficients for the camera

• obj_pts (numpy.ndarray, shape (n, 3), float) – List of 3d points. Points are relative to the object frame

• cal_area_is_safe (callable) – alpha_shape_is_safe function that takes img_pts as an array, (shape (n, 2)) of floats and returns an array-like object of booleans. return[i] corresonds to img_pts[i]. If return[i] is True, then img_pts[i] is within the safe internal calibration image area. If it is False, it is not within that safe area

• cal_vol_is_safe (callable) – alpha_shape_is_safe function that takes obj_pts and returns a array-like object of booleans. return[i] corresonds to img_pts[i]. If return[i] is True, then img_pts[i] is within the safe internal calibration 3D volume. If it is False, it is not within that safe volume

• critical_pt (str, optional) –

  Criteria for step 3. Must be one of:

  • If ‘first’ then obj_pts cannot have a homogeneous coordinate with a magnitude past the first maxima of the distortion curve. This is the most useful option for the majority of lenses.

  • If ‘infinity’, the magnitude must be less than the final maxima of the distortion curve, and the distortion curve must be decreasing after the final maxima. This is the most useful option for mustache or otherwise complex distortion, if the mustache distortion effect is accurate

  • If None, step 3 will be omitted. If cal_area_is_safe and cal_vol_is_safe are available (and not dummy return True functions from incal_calibration_bounds_debug()), the step 3 check is likely unnecessary

Returns

obj_pts_safe – Array of booleans where return[i] cooresponds to obj_pts[i]. If return[i] is True, obj_pts[i] is well behaved. If return[i] is False, obj_pts[i] may not be well behaved

Return type

numpy.ndarray, shape (n,), bool

See also

incal_calibration_bounds

creates alpha_shape_is_safe functions

incal_calibration_bounds(calibio_path, cal_vol_alpha, cal_area_alpha, dof=None, num_vol_figs=10)

Creates objects that determines if a point is inside the calibration regions

From the calibio_path, the 3D points from the calibration board are used to define the safe 3D volume. The 2D points of the image detections are used to define the safe image area. The area/volume are defined using an alpha shape (technically an alpha complex). An alpha shape is similar to a convex hull, but sets a limit on the distance between two vertices for them to be connected. The max distances for the volume and area is 1 / cal_vol_alpha and 1 / cal_area_alpha respectively.

If the global variable debug_show_cal_bounds is True, this method also creates debug images.

One debug image is created for the safe image area. That image is green for pixels inside the ‘safe’ region and red for pixels outside the safe region. The region is not discretized to pixels, so the image is a (good) approximation.

Several debug images are created for the safe 3D volume. Each debug image is a slice of the 3D safe object. The slices are done at planes progressively farther from the camera (not spherical shells of constant distance from the camera). Points in the field of view (not accounting for lens distortion) are given. Points colored red are unsafe. Points colored green are safe.

Generates the following images when debug_show_cal_bounds (global) is True:

3d_cal_points_camera.png

A scatter plot of the internal calibration points as viewed from the camera position. X is the real world position relative to the camera horizontal axis. Z is the real world position relative to the camera optical axis.

3d_cal_points_side.png

A scatter plot of the internal calibration points as viewed from a location to the side of the camera. X is the real world position relative to the camera horizontal axis. Y is the real world position relative to the camera vertical axis.

image_area.png

The safe and unsafe locations in the image based on the internal calibration points and the cal_area_alpha parameter

unsafe_volume_Z=*_inches.png

Where * is Z location of the planar slice in inches for the given image. These images are like a wedding cake stack of the 3D calibration volume. Each image is a slice of the volume at a given Z distance from the camera. The image shows the safe and unsafe locations in that planar slice.

Parameters

• calibio_path (str) – Path to the calib.io saved calibration json

• cal_vol_alpha (float) – Used to define the 3D volume alpha shape. Alpha parameter is 1 / cal_vol_alpha

• cal_area_alpha (float) – Used to define the 3D image area alpha shape. Alpha parameter is 1 / cal_vol_alpha

• dof (tuple, optional) – Depth of field. Optional, but must be given if global variable debug_show_cal_bounds is True since it is used to generate debug images. The first item of tuple is distance to the first slice of the 3D volume. The second item is distance to the last slice. The slices are done in planes (not in spherical shells of constant distance to the camera).

• num_vol_figs (int, optional) – Number of volume figures. Optional, but must be given if global variable debug_show_cal_bounds is True since it is used to generate debug images. The debug images of the calibration volume slice the volume into planes at progressively farther distances. This input determines the number of slices

Returns

• cal_area_is_safe (callable) – Function that takes image points in an array-like object and returns a corresponding array of bools indicating which points are safe.

• cal_vol_is_safe (callable) – Function that takes 3D points in an array-like object and returns a corresponding array of bools indicating which points are safe.

incal_calibration_bounds_debug()

Returns debugging incal_calibration_bounds() objects

The returned incal_calibration_bounds() functions True for every input point

incal_from_calibio(calibio_path)

Returns the internal calibration values from the calib.io output json

Parameters

calibio_path (str) – Path to the calib.io saved calibration json

Returns

• img_size (numpy.ndarray, shape (2,)) – Image size (height, width)

• uPSP_cameraMatrix (numpy.ndarray, shape (3, 3)) – Camera matrix for uPSP applications (same as openCV cameraMatrix, but cx and cy are vectors from image center to principal point rather than the principal point itself).

• distCoeffs (numpy.ndarray, shape (5, 1)) – openCV distortion coefficients

uncertainties_from_calibio(calibio_path)

Returns uncertainties for OpenCV terms

Parameters

calibio_path (str) – Path to the calib.io saved calibration json

Returns

Standard deviation of calibration terms: (focal length, principal point x, principal point y, k1, k2, p1, p2, k3)

Return type

tuple

write_incal_from_calibio(calibio_path, camera_name, sensor_size, save_dir=None)

Writes the internal calibration to a json file

Saves internal calibration as '{camera_name}.json' to save_dir

Parameters

• calibio_path (str) – Path to the calib.io saved calibration json

• camera_name (str) – Name of the camera

• sensor_size (numpy.ndarray, shape (2,) of floats) – Physical size of the image sensor in inches

• save_dir (str, optional) – Path of directory to save the internal calibration json file. If None, save_dir is set to the directory containing the Calib.io json