simplestereo package

Module contents

simplestereo

Module initialization.

Documentation DOCSTRING follows numpy-style wherever possible. See https://numpydoc.readthedocs.io/en/latest/format.html

Submodules

simplestereo._rigs module

_rigs

Main classes loaded at package level.

See :py:module:`__init__.py`.

Todo

• Add new rig class for uncalibrated stereo.

class simplestereo._rigs.RectifiedStereoRig(Rcommon, rectHomography1, rectHomography2, *args)

Bases: StereoRig

Keep together and manage all parameters of a calibrated and rectified stereo rig.

It includes all the parameters of StereoRig plus two rectifying homographies. Differently from OpenCV, here the rectifying homographies (pixel domain) are taken as input, the ones commonly referred in literature, and not the rectification transformation in the object space.

Parameters:

• Rcommon (numpy.ndarray) – 3x3 matrices representing the new common camera orientation after rectification.

• rectHomography1 (numpy.ndarray) – 3x3 rectification homographies.

• rectHomography2 (numpy.ndarray) – 3x3 rectification homographies.

• StereoRig (StereoRig or sequence) – A StereoRig object or, alternatively, all the parameters of simplestereo.StereoRig() (in the same order).

Attributes:

E

F

R

Rcommon

T

distCoeffs1

distCoeffs2

intrinsic1

intrinsic2

rectHomography1

rectHomography2

Methods

computeRectificationMaps([destDims, alpha])	Compute the two maps to undistort and rectify the stereo pair.
fromFile(filepath)	Alternative initialization of StereoRigRectified object from JSON file.
get3DPoints(disparityMap)	Get the 3D points in the space from the disparity map.
getBaseline()	Calculate the norm of the vector from camera 1 to camera 2.
getCenters()	Calculate camera centers in world coordinates.
getEssentialMatrix()	Returns the essential matrix E.
getFundamentalMatrix()	Returns the fundamental matrix F.
getProjectionMatrices()	Calculate the projection matrices of camera 1 and camera 2.
getRectifiedProjectionMatrices()	Calculate the projection matrices of camera 1 and camera 2 after rectification.
rectifyImages(img1, img2[, interpolation])	Undistort, rectify and apply affine transformation to a couple of images coming from the stereo rig.
save(filepath)	Save configuration to JSON file.
undistortImages(img1, img2[, changeCameras, ...])	Undistort two given images of the stereo rig.

property Rcommon

computeRectificationMaps(destDims=None, alpha=1)

Compute the two maps to undistort and rectify the stereo pair.

This method wraps cv2.initUndistortRectifyMap() plus a custom fitting algorithm to keep image within dimensions. It modifies the original camera matrix applying affine transformations (x-y scale and translation, shear (x axis only)) without losing rectification. The two new maps are stored internally. This method is called in the constructor with default parameters and can be called later to change its settings.

Parameters:

• destDims (tuple, optional) – Resolution of destination images as (width, height) tuple (default to first image resolution).

• alpha (float, optional) – Scaling parameter between 0 and 1 to be applied to both images. If alpha=1 (default), the corners of the original images are preserved. If alpha=0, only valid rectangle is made visible. Intermediate values produce a result in the middle. Extremely skewed camera positions do not work well with alpha<1.

Return type:

None

Notes

OpenCV uses rectification transformation in the object space (3x3 matrix), but most of the papers provide algorithms to compute the homography to be applied to the image in a pixel domain, not a rotation matrix R in 3D space. This library always refers to rectification transform as the ones in pixel domain. To adapt it to be used with OpenCV the transformation to be used in cv2.initUndistortRectifyMap() (and other functions) is given by rectHomography.dot(cameraMatrix). For each camera, the function computes homography H as the rectification transformation.

classmethod fromFile(filepath)

Alternative initialization of StereoRigRectified object from JSON file.

Parameters:

filepath (str) – Path of the JSON file containing saved parameters of the stereo rig.

Returns:

An object of StereoRigRectified class.

Return type:

StereoRigRectified

get3DPoints(disparityMap)

Get the 3D points in the space from the disparity map.

If the calibration was done with real world units (e.g. millimeters), the output would be in the same units. The world origin will be in the left camera.

Parameters:

disparityMap (numpy.ndarray) – A dense disparity map having same height and width of images.

Returns:

Array of points having shape (height,width,3), where at each y,x coordinates a (x,y,z) point is associated.

Return type:

numpy.ndarray

getRectifiedProjectionMatrices()

Calculate the projection matrices of camera 1 and camera 2 after rectification.

New projection matrices, after rectification, share the same orientation Rcommon, have only one horizontal displacement (the baseline) and have new intrinsics that depends on all the rigid manipulation done after rectification.

Returns:

• numpy.ndarray – The 3x4 projection matrix of the first camera.

• numpy.ndarray – The 3x4 projection matrix of the second camera.

property rectHomography1

property rectHomography2

rectifyImages(img1, img2, interpolation=<MagicMock id='140629303654224'>)

Undistort, rectify and apply affine transformation to a couple of images coming from the stereo rig.

img1 and img2 must be provided as in calibration (es. img1 is the left image, img2 the right one). This method is wraps cv2.remap() for two images of the stereo pair. The maps used are computed by computeRectificationMaps() during initialization (with default parameters). computeRectificationMaps() can be called before calling this method to change mapping settings (e.g. final resolution).

Parameters:

• img1 (cv2.Mat) – A couple of OpenCV images taken with the stereo rig (ordered).

• img2 (cv2.Mat) – A couple of OpenCV images taken with the stereo rig (ordered).

• interpolation (int, optional) – OpenCV InterpolationFlag. The most common are cv2.INTER_NEAREST, cv2.INTER_LINEAR (default) and cv2.INTER_CUBIC.

Returns:

img1_rect, img2_rect – The undistorted images.

Return type:

cv2.Mat

save(filepath)

Save configuration to JSON file.

Save the current stereo rig configuration to a JSON file that can be loaded later.

Parameters:

filepath (str) – Path where to save the JSON file containing the parameters of the stereo rig.

class simplestereo._rigs.StereoRig(res1, res2, intrinsic1, intrinsic2, distCoeffs1, distCoeffs2, R, T, F=None, E=None, reprojectionError=None)

Bases: object

Keep together and manage all parameters of a calibrated stereo rig.

The essential E and fundamental F matrices are optional as they are not always available. They may be computed from camera parameters, if needed.

Parameters:

• res1 (sequence) – Resolution of camera as (width, height)

• res2 (sequence) – Resolution of camera as (width, height)

• intrinsic1 (list or numpy.ndarray) – 3x3 intrinsic camera matrix in the form [[fx, 0, tx], [0, fy, ty], [0, 0, 1]].

• intrinsic2 (list or numpy.ndarray) – 3x3 intrinsic camera matrix in the form [[fx, 0, tx], [0, fy, ty], [0, 0, 1]].

• distCoeffs1 (list or numpy.ndarray) – List of distortion coefficients of 4, 5, 8, 12 or 14 elements (refer to OpenCV documentation).

• distCoeffs2 (list or numpy.ndarray) – List of distortion coefficients of 4, 5, 8, 12 or 14 elements (refer to OpenCV documentation).

• R (list or numpy.ndarray.) – 3x3 rotation matrix of shape between the 1st and the 2nd camera coordinate systems.

• T (list or numpy.ndarray) – Translation vector between the coordinate systems of the cameras.

• E (numpy.ndarray, optional) – Essential matrix as numpy.ndarray (default None) .

• F (numpy.ndarray, optional) – Fundamental matrix as numpy.ndarray (default None).

• reprojectionError (float, optional) – Total reprojection error resulting from calibration (default None).

• note:: (..) – This class follows OpenCV convention to set the origin of the world coordinate system into the first camera. Hence the first camera extrinsics parameters will always be identity matrix rotation and zero translation. If your world coordinate system is placed into a camera, you must convert it to use this class (see simplestereo.utils.moveExtrinsicOriginToFirstCamera()).

Attributes:

E

F

R

T

distCoeffs1

distCoeffs2

intrinsic1

intrinsic2

Methods

fromFile(filepath)	Alternative initialization of StereoRig object from JSON file.
getBaseline()	Calculate the norm of the vector from camera 1 to camera 2.
getCenters()	Calculate camera centers in world coordinates.
getEssentialMatrix()	Returns the essential matrix E.
getFundamentalMatrix()	Returns the fundamental matrix F.
getProjectionMatrices()	Calculate the projection matrices of camera 1 and camera 2.
save(filepath)	Save configuration to JSON file.
undistortImages(img1, img2[, changeCameras, ...])	Undistort two given images of the stereo rig.

property E

property F

property R

property T

property distCoeffs1

property distCoeffs2

classmethod fromFile(filepath)

Alternative initialization of StereoRig object from JSON file.

Parameters:

filepath (str) – Path of the JSON file containing saved parameters of the stereo rig.

Returns:

An object of StereoRig class.

Return type:

StereoRig

getBaseline()

Calculate the norm of the vector from camera 1 to camera 2.

Returns:

Length of the baseline in world units.

Return type:

float

getCenters()

Calculate camera centers in world coordinates.

Anyway first camera will always be centered in zero (returned anyway).

Returns:

• numpy.ndarray – 3D coordinates of first camera center (always zero).

• numpy.ndarray – 3D coordinates of second camera center.

getEssentialMatrix()

Returns the essential matrix E.

If not set, E is computed from the fundamental matrix F and the camera matrices.

Returns:

E – The 3x3 essential matrix.

Return type:

numpy.ndarray

Notes

The essential matrix has always a free scaling factor.

getFundamentalMatrix()

Returns the fundamental matrix F.

If not set, F is computed from projection matrices using simplestereo.calibration.getFundamentalMatrixFromProjections().

Returns:

F – The 3x3 fundamental matrix.

Return type:

numpy.ndarray

Notes

The fundamental matrix has always a free scaling factor.

getProjectionMatrices()

Calculate the projection matrices of camera 1 and camera 2.

Returns:

• numpy.ndarray – The 3x4 projection matrix of the first camera.

• numpy.ndarray – The 3x4 projection matrix of the second camera.

property intrinsic1

property intrinsic2

save(filepath)

Save configuration to JSON file.

Save the current stereo rig configuration to a JSON file that can be loaded later.

Parameters:

filepath (str) – Path where to save the JSON file containing the parameters of the stereo rig.

undistortImages(img1, img2, changeCameras=False, alpha=1, destDims=None, centerPrincipalPoint=False)

Undistort two given images of the stereo rig.

This method wraps cv2.getOptimalNewCameraMatrix() followed by cv2.undistort() for both images. If changeCameras is False, original camera matrices are used, otherwise all the parameters of cv2.getOptimalNewCameraMatrix() are considered when undistorting the images.

Parameters:

• img1 (cv2.Mat) – A couple of OpenCV images taken with the stereo rig (ordered).

• img2 (cv2.Mat) – A couple of OpenCV images taken with the stereo rig (ordered).

• changeCameras (bool) – If False (default) the original camera matrices are used and all the following parameters are skipped. If True, new camera matrices are computed with the given parameters.

• alpha (float) – Scaling parameter for both images. If alpha=0, it returns undistorted image with minimum unwanted pixels (so it may even remove some pixels at image corners). If alpha=1, all pixels are retained with some extra black images. Values in the middle are accepted too (default to 1).

• destDims (tuple, optional) – Resolution of destination images as (width, height) tuple (default to first image resolution).

• centerPrincipalPoint (bool) – If True the principal point is centered within the images (default to False).

Returns:

• img1_undist, img2_undist (cv2.Mat) – The undistorted images.

• cameraMatrixNew1, cameraMatrixNew2 (numpy.ndarray) – If changeCameras is set to True, the new camera matrices are returned too.

See also

cv2.getOptimalNewCameraMatrix, cv2.undistort

class simplestereo._rigs.StructuredLightRig(r)

Bases: StereoRig

StereoRig child class with structured light methods.

Attributes:

E

F

R

T

distCoeffs1

distCoeffs2

intrinsic1

intrinsic2

Methods

fromFile()	Alternative initialization of StereoRig object from JSON file.
getBaseline()	Calculate the norm of the vector from camera 1 to camera 2.
getCenters()	Calculate camera centers in world coordinates.
getEssentialMatrix()	Returns the essential matrix E.
getFundamentalMatrix()	Returns the fundamental matrix F.
getProjectionMatrices()	Calculate the projection matrices of camera 1 and camera 2.
save(filepath)	Save configuration to JSON file.
triangulate(camPoints, projPoints)	Given camera-projector correspondences, proceed with triangulation.
undistortCameraImage(imgObj)	Undistort camera image.
undistortImages(img1, img2[, changeCameras, ...])	Undistort two given images of the stereo rig.

fromFile()

Alternative initialization of StereoRig object from JSON file.

Parameters:

filepath (str) – Path of the JSON file containing saved parameters of the stereo rig.

Returns:

An object of StereoRig class.

Return type:

StereoRig

triangulate(camPoints, projPoints)

Given camera-projector correspondences, proceed with triangulation.

Parameters:

• camPoints (numpy.ndarray) – Ordered corresponding coordinates as (x, y) couples from camera and projector. Last dimension must be 2. Camera points must be already undistorted.

• projPoints (numpy.ndarray) – Ordered corresponding coordinates as (x, y) couples from camera and projector. Last dimension must be 2. Camera points must be already undistorted.

Return type:

3D coordinates with shape (-1, 1, 3).

undistortCameraImage(imgObj)

Undistort camera image.

Parameters:

imgObj (numpy.ndarray) – Camera image.

Return type:

Undistorted image.

simplestereo.active module

active

Contains classes to manage active stereo algorithms and helper functions. This module contains both conventional active stereo (2 cameras + projector) and structured-light (1 camera + projector) methods.

class simplestereo.active.GrayCode(rig, black_thr=40, white_thr=5)

Bases: object

Wrapper for the Gray code method from OpenCV.

Structured-light implementation using camera-projector calibrated rig.

Parameters:

• rig (StereoRig) – A stereo rig object with camera in position 1 (world origin) and projector in position 2.

• black_thr (int, optional) – Black threshold is a number between 0-255 that represents the minimum brightness difference required for valid pixels, between the fully illuminated (white) and the not illuminated images (black); used in computeShadowMasks method. Default to 40.

• white_thr (int, optional) – White threshold is a number between 0-255 that represents the minimum brightness difference required for valid pixels, between the graycode pattern and its inverse images; used in getProjPixel method. Default to 5.

Note

Projector distortion may be unaccurate, especially along border. If this is the case, you can ignore it setting rig.distCoeffs2 == None before passing rig to the constructor or setting a narrow roi.

Methods

getCloud(images[, roi])

Perform the 3D point calculation from a list of images.

getCloud(images, roi=None)

Perform the 3D point calculation from a list of images.

Parameters:

• images (list or tuple) – A list of image paths acquired by the camera. Each set must be ordered like all the Gray code patterns (see cv2.structured_light_GrayCodePattern). Any following extra image will be ignored (es. full white).

• roi (tuple, optional) – Region of interest in the format (x,y,width,height) where x,y is the upper left corner. Default to None.

Returns:

Points with shape (n,1,3)

Return type:

numpy.ndarray

Todo

Add possibility to return point cloud in same image/roi shape with NaN in invalid locations.

class simplestereo.active.GrayCodeDouble(rig, projRes, black_thr=40, white_thr=5)

Bases: object

Wrapper for the Gray code method from OpenCV.

Conventional active stereo implementation, i.e. using two calibrated cameras and one uncalibrated projector.

Parameters:

• rig (StereoRig) – A stereo rig object with two cameras.

• projRes (tuple) – Projector resolution as (width, height).

• black_thr (int, optional) – Black threshold is a number between 0-255 that represents the minimum brightness difference required for valid pixels, between the fully illuminated (white) and the not illuminated images (black); used in computeShadowMasks method. Default to 40.

• white_thr (int, optional) – White threshold is a number between 0-255 that represents the minimum brightness difference required for valid pixels, between the graycode pattern and its inverse images; used in getProjPixel method. Default to 5.

Todo

Projector distortion may be unaccurate, especially along border. If this is the case, you can ignore it setting rig.distCoeffs2 == None before passing rig to the constructor or setting a narrow roi.

Methods

getCloud(images[, roi1, roi2])

Perform the 3D point calculation from a list of images.

getCloud(images, roi1=None, roi2=None)

Perform the 3D point calculation from a list of images.

Parameters:

• images (list or tuple) – A list (or tuple) of 2 dimensional tuples (ordered left and right) of image paths, e.g. [(“oneL.png”,”oneR.png”), (“twoL.png”,”twoR.png”), …] Each set must be ordered like all the Gray code patterns (see cv2.structured_light_GrayCodePattern). Any following extra image will be ignored (es. full white).

• roi1 (tuple, optional) – Region of interest on camera 1 in the format (x,y,width,height) where x,y is the upper left corner. Default to None.

• roi2 (tuple, optional) – As roi1, but for camera 2.

Returns:

Points with shape (n,1,3)

Return type:

numpy.ndarray

simplestereo.active.GrayCodeSingle

alias of GrayCode

class simplestereo.active.StereoFTP(stereoRig, fringe, period, shift=0, stripeColor='red', stripeSensitivity=0.5)

Bases: object

Manager of the Stereo Fourier Transform Profilometry.

Parameters:

• stereoRig (StereoRig) – A stereo rig object with camera in position 1 (world origin) and projector in position 2.

• fringeDims (tuple) – Dimensions of projector image as (width, height).

• period (float) – Period of the fringe (in pixels).

• stripeColor (str, optional) – BGR color used for the central stripe to be chosen among “blue”, “green” or “red”. Also “b”, “g”, “r” accepted. Default to “red”.

• stripeSensitivity (float, optional) – Sensitivity to find the stripe. See findCentralStripe().

Note

Working details in the paper Pasquale Lafiosca et al., “Automated Aircraft Dent Inspection via a Modified Fourier Transform Profilometry Algorithm”, Sensors, 2022, https://doi.org/10.3390/s22020433

Methods

convertGrayscale(img)	Convert to grayscale using max.
getCloud(imgObj[, radius_factor, roi, ...])	Process an image and get the point cloud.

static convertGrayscale(img)

Convert to grayscale using max.

This keeps highest BGR value over the central stripe (e.g. (0,0,255) -> 255), allowing the FFT to work properly.

Parameters:

image (numpy.ndarray) – BGR image.

Returns:

Grayscale image.

Return type:

numpy.ndarray

Todo

Gamma correction may be implemented as a parameter.

Note

I’ve tried different approaches, but the simple max works best at converting the stripe to white.

getCloud(imgObj, radius_factor=0.5, roi=None, unwrappingMethod=None, plot=False)

Process an image and get the point cloud.

Parameters:

• imgObj (numpy.ndarray) – BGR image acquired by the camera.

• radius_factor (float, optional) – Radius factor of the pass-band filter. Default to 0.5.

• roi (tuple, optional) – Region of interest in the format (x,y,width,height) where x,y is the upper left corner. Default to None.

• unwrappingMethod (function, optional) – Pointer to chosen unwrapping function. It must take the phase as the only argument. If None (default), `np.unwrap`is used.

Returns:

• Point cloud with shape (height,width,3), with height and width

• same as the input image or selected roi.

class simplestereo.active.StereoFTPAnaglyph(stereoRig, fringe, period, shift=0, stripeColor='red', stripeSensitivity=0.5)

Bases: StereoFTP

Manager of the Stereo Fourier Transform Profilometry using an anaglyph pattern build with buildAnaglyphFringe().

Parameters:

• stereoRig (StereoRig) – A stereo rig object with camera in position 1 (world origin) and projector in position 2.

• fringeDims (tuple) – Dimensions of projector image as (width, height).

• period (float) – Period of the fringe (in pixels).

• stripeColor (str, optional) – BGR color used for the central stripe to be chosen among “blue”, “green” or “red”. Also “b”, “g”, “r” accepted. Default to “red”.

• stripeSensitivity (float, optional) – Sensitivity to find the stripe. See findCentralStripe().

Note

This is a work in progress.

Methods

convertGrayscale(img)	Convert to grayscale using Guo et al., "Improved fourier transform profilometry for the automatic measurement of 3D object shapes", 1990.
getCloud(imgObj[, radius_factor, roi, ...])	Process an anaglyph image and get the point cloud.

static convertGrayscale(img)

Convert to grayscale using Guo et al., “Improved fourier transform profilometry for the automatic measurement of 3D object shapes”, 1990.

Parameters:

image (numpy.ndarray) – BGR image.

Returns:

Grayscale image as float.

Return type:

numpy.ndarray

Todo

Gamma correction may be implemented as a parameter.

getCloud(imgObj, radius_factor=0.5, roi=None, unwrappingMethod=None, plot=False)

Process an anaglyph image and get the point cloud.

The pattern expected to be projected on the object is the one produced by :func:buildAnaglyphFringe.

Parameters:

• imgObj (numpy.ndarray) – BGR image acquired by the camera.

• radius_factor (float, optional) – Radius factor of the pass-band filter. Default to 0.5.

• roi (tuple, optional) – Region of interest in the format (x,y,width,height) where x,y is the upper left corner. Default to None.

• unwrappingMethod (function, optional) – Pointer to chosen unwrapping function. It must take the phase as the only argument. If None (default), `np.unwrap`is used.

Returns:

• Point cloud with shape (height,width,3), with height and width

• same as the input image or selected roi.

class simplestereo.active.StereoFTP_Mapping(stereoRig, fringe, period, shift=0, stripeColor='red', stripeSensitivity=0.5)

Bases: StereoFTP

Manager of the classic Stereo Fourier Transform Profilometry.

Classic method (does not use a virtual reference plane) but it does use the automatic band-pass estimation.

Parameters:

• stereoRig (StereoRig) – A stereo rig object with camera in position 1 (world origin) and projector in position 2.

• fringeDims (tuple) – Dimensions of projector image as (width, height).

• period (float) – Period of the fringe (in pixels).

• stripeColor (str, optional) – BGR color used for the central stripe to be chosen among “blue”, “green” or “red”. Also “b”, “g”, “r” accepted. Default to “red”.

• stripeSensitivity (float, optional) – Sensitivity to find the stripe. See findCentralStripe().

Methods

convertGrayscale(img)	Convert to grayscale using max.
getCloud(imgObj[, radius_factor, roi, ...])	Process an image and get the point cloud.

getCloud(imgObj, radius_factor=0.5, roi=None, unwrappingMethod=None, plot=False)

Process an image and get the point cloud.

Parameters:

• imgObj (numpy.ndarray) – BGR image acquired by the camera.

• radius_factor (float, optional) – Radius factor of the pass-band filter. Default to 0.5.

• roi (tuple, optional) – Region of interest in the format (x,y,width,height) where x,y is the upper left corner. Default to None.

• unwrappingMethod (function, optional) – Pointer to chosen unwrapping function. It must take the phase as the only argument. If None (default), `np.unwrap`is used.

Returns:

• Point cloud with shape (height,width,3), with height and width

• same as the input image or selected roi.

class simplestereo.active.StereoFTP_PhaseOnly(stereoRig, fringe, period, shift=0, stripeColor='red', stripeSensitivity=0.5)

Bases: object

Manager of the Stereo Fourier Transform Profilometry.

Parameters:

• stereoRig (StereoRig) – A stereo rig object with camera in position 1 (world origin) and projector in position 2.

• fringeDims (tuple) – Dimensions of projector image as (width, height).

• period (float) – Period of the fringe (in pixels).

• stripeColor (str, optional) – BGR color used for the central stripe to be chosen among “blue”, “green” or “red”. Also “b”, “g”, “r” accepted. Default to “red”.

• stripeSensitivity (float, optional) – Sensitivity to find the stripe. See findCentralStripe().

Methods

convertGrayscale(img)	Convert to grayscale using max.
getPhase(imgObj[, radius_factor, roi, plot])	Process an image and get the point cloud.

static convertGrayscale(img)

Convert to grayscale using max.

This keeps highest BGR value over the central stripe (e.g. (0,0,255) -> 255), allowing the FFT to work properly.

Parameters:

image (numpy.ndarray) – BGR image.

Returns:

Grayscale image.

Return type:

numpy.ndarray

Todo

Gamma correction may be implemented as a parameter.

getPhase(imgObj, radius_factor=0.5, roi=None, plot=False)

Process an image and get the point cloud.

Parameters:

• imgObj (numpy.ndarray) – BGR image acquired by the camera.

• radius_factor (float, optional) – Radius factor of the pass-band filter. Default to 0.5.

• roi (tuple, optional) – Region of interest in the format (x,y,width,height) where x,y is the upper left corner. Default to None.

Returns:

• Point cloud with shape (height,width,3), with height and width

• same as the input image or selected roi.

simplestereo.active.buildAnaglyphFringe(period=10, shift=0, dims=(1280, 720), vertical=False, dtype=<MagicMock id='140629304635216'>)

Build sinusoidal anaglyph fringe image.

Assumes BGR images, using blue and red as complementary colors and green as central stripe. This allows to actually extract three different images from a single scan. Red and blue can be subtracted to suppress DC component. Green serves the purpose to obtain a reference phase in the FTP algorithm.

Parameters:

• period (float) – Fringe period along x axis, in pixels.

• shift (float) – Shift to apply. Default to 0.

• dims (tuple) – Image dimensions as (width, height).

• vertical (bool) – If True, fringe is build along vertical. Default to False (horizontal).

• dtype (numpy.dtype) – Image is scaled in the range 0 - max value to match dtype. Default np.uint8 (max 255).

Returns:

Fringe image.

Return type:

numpy.ndarray

simplestereo.active.buildBinaryFringe(period=10, shift=0, dims=(1280, 720), vertical=False, stripeColor=None, dtype=<MagicMock id='140629301773840'>)

Build binary fringe image.

Parameters:

• period (int) – Fringe period along x axis, in pixels. An integer is expected. If a float is passed, it will be converted to integer.

• shift (float) – Shift to apply. Default to 0.

• dims (tuple) – Image dimensions as (width, height).

• vertical (bool) – If True, fringe is build along vertical. Default to False (horizontal fringe direction).

• stripeColor (str, optional) – Color of the stripe chosen from ‘blue’,’green’ or ‘red’. Also ‘b’, ‘g’, ‘r’ are accepted. Default to None (no stripe drawn).

• dtype (numpy.dtype) – Image is scaled in the range 0 - max value to match dtype. Default np.uint8 (max 255).

Returns:

Fringe image.

Return type:

numpy.ndarray

simplestereo.active.buildFringe(period, shift=0, dims=(1280, 720), vertical=False, stripeColor=None, dtype=<MagicMock id='140629301801616'>)

Build sinusoidal fringe image.

Parameters:

• period (float) – Fringe period along x axis, in pixels.

• shift (float, optional) – Shift to apply. Default to 0.

• dims (tuple, optional) – Image dimensions as (width, height). Default to (1280,720).

• vertical (bool, optional) – If True, fringe is build along vertical. Default to False (horizontal).

• stripeColor (str, optional) – Color of the stripe chosen from ‘blue’,’green’ or ‘red’. Also ‘b’, ‘g’, ‘r’ are accepted. Default to None (no stripe drawn).

• dtype (numpy.dtype) – Image is scaled in the range 0 - max value to match dtype. Default np.uint8 (max 255).

Returns:

Fringe image.

Return type:

numpy.ndarray

simplestereo.active.computeROI(img, blackThreshold=10, extraMargin=0)

Exclude black regions along borders.

Usually the projector does not illuminate the whole image area. This function attempts to find the region of interest as a rectangle inside the biggest contour.

Parameters:

• img (numpy.ndarray) – Camera image with black borders.

• blackThreshold (int, optional) – Threshold for the black regions between 0 and 255. Default to 10.

• extraMargin (int, optional) – Extra safety margin to reduce to ROI. Default to 0.

Returns:

• tuple – ROI as tuple of integers (x,y,w,h).

• .. note:: To rewrite completely. Not suitable for production.

simplestereo.active.findCentralStripe(image, color='r', sensitivity=0.5, interpolation='linear')

Find coordinates of a colored stripe in the image.

Search is done with subpixel accuracy only along the x-axis direction.

Parameters:

• image (numpy.ndarray) – BGR image with a colored vertical stripe.

• color (str, optional) – Color of the original stripe as ‘blue’,’green’ or ‘red’. Also ‘b’, ‘g’, ‘r’ are accepted. Default to ‘red’.

• sensitivity (float, optional) – Sensitivity for color matching in [0,1]. Default to 0.5.

• interpolation (str) – See scipy.interpolate.interp1d kind parameter.

Returns:

x,y coordinates of stripe centers with shape (n,2).

Return type:

numpy.ndarray

Note

The search is done along a single dimension, the x-axis. Missing values are filled with nearest-value interpolation.

simplestereo.active.generateGrayCodeImgs(targetDir, resolution)

Generate Gray Codes and save it to PNG images.

Starts from the couple of images 0.png and 1.png (one is the inverse of the other). Then 2.png is coupled with 3.png and so on. First half contains vertical stripes, followed by horizontal ones. The function stores also a black.png and white.png images for threshold calibration.

Parameters:

• targetDir (string) – Path to the directory where to save Gray codes. Directory is created if not exists.

• resolution (tuple) – Pixel dimensions of the images as (width, height) tuple (to be matched with projector resolution).

Returns:

Number of generated patterns (black and white are not considered in this count).

Return type:

int

simplestereo.calibration module

calibration

Contains different calibration algorithms.

Todo

Implement circles calibration. N.B. after using cv2.findCirclesGrid() a point refinement algorithm is needed (like cv2.cornerSubPix() does for the chessboard).

simplestereo.calibration.chessboardProCam(images, projectorResolution, chessboardSize=(6, 7), squareSize=1, black_thr=40, white_thr=5, camIntrinsic=None, camDistCoeffs=None)

Performs stereo calibration between a camera (reference) and a projector.

Adapted from the code available (MIT licence) at https://github.com/kamino410/procam-calibration and based on the paper of Daniel Moreno and Gabriel Taubin, “Simple, accurate, and robust projector-camera calibration”, DOI: 10.1109/3DIMPVT.2012.77. The camera will be put in world origin.

Parameters:

• images (list or tuple) – A list of lists (one per set) of image paths acquired by the camera. Each set must be ordered like all the Gray code patterns (see cv2.structured_light_GrayCodePattern) followed by black, normal light and white images (in this order). At least 5-6 sets are suggested.

• projectorResolution (tuple) – Projector pixel resolution as (width, height).

• chessboardSize (tuple, optional) – Chessboard internal dimensions as (width, height). Dimensions should be different to avoid ambiguity. Default to (7,6).

• squareSize (float, optional) – If the square size is known, calibration can be in metric units. Default to 1.

• black_thr (int, optional) – Black threshold is a number between 0-255 that represents the minimum brightness difference required for valid pixels, between the fully illuminated (white) and the not illuminated images (black). Default to 40.

• white_thr (int, optional) – White threshold is a number between 0-255 that represents the minimum brightness difference required for valid pixels, between the graycode pattern and its inverse images. Default to 5.

• camIntrinsic (numpy.ndarray, optional) – A 3x3 matrix representing camera intrinsic parameters. If not given it will be calculated.

• camDistCoeffs (list, optional) – Camera distortion coefficients of 4, 5, 8, 12 or 14 elements (refer to OpenCV documentation). If not given they will be calculated.

• normalize (bool) – If True, the images are min-max normalized before processing. Default to False.

Returns:

• StereoRig – A StereoRig object

• .. todo:: – Iteratively exclude images that have high reprojection errors and re-calibrate.

simplestereo.calibration.chessboardProCamWhite(images, projectorResolution, chessboardSize=(6, 7), squareSize=1, black_thr=40, white_thr=5, camIntrinsic=None, camDistCoeffs=None, extended=False)

Performs stereo calibration between a camera (reference) and a projector.

Requires a chessboard with black top-left square. Adapted from the code available (MIT licence) at https://github.com/kamino410/procam-calibration and based on the paper of Daniel Moreno and Gabriel Taubin, “Simple, accurate, and robust projector-camera calibration”, DOI: 10.1109/3DIMPVT.2012.77. The camera will be put in world origin.

Parameters:

• images (list or tuple) – A list of lists (one per set) of image paths acquired by the camera. Each set must be ordered like all the Gray code patterns (see cv2.structured_light_GrayCodePattern) followed by black, normal light conditions and white images (in this exact order). At least 5-6 sets are suggested.

• projectorResolution (tuple) – Projector pixel resolution as (width, height).

• chessboardSize (tuple, optional) – Chessboard internal dimensions as (cols, rows). Dimensions should be different to avoid ambiguity. Default to (6,7).

• squareSize (float, optional) – If the square size is known, calibration can be in metric units. Default to 1.

• black_thr (int, optional) – Black threshold is a number between 0-255 that represents the minimum brightness difference required for valid pixels, between the fully illuminated (white) and the not illuminated images (black); used in computeShadowMasks method. Default to 40.

• white_thr (int, optional) – White threshold is a number between 0-255 that represents the minimum brightness difference required for valid pixels, between the graycode pattern and its inverse images; used in getProjPixel method. Default to 5.

• camIntrinsic (list, optional) – A 3x3 matrix representing camera intrinsic parameters. If not given it will be calculated.

• camIntrinsic – Camera distortion coefficients of 4, 5, 8, 12 or 14 elements (refer to OpenCV documentation). If not given they will be calculated.

• extended (bool) – If True, perViewErrors of the stereo calibration are returned. Default to False.

Returns:

• StereoRig – A StereoRig object

• perViewErrors – Returned only if extended is True. For each pattern view, the RMS error of camera and projector is returned.

simplestereo.calibration.chessboardSingle(images, chessboardSize=(6, 7), squareSize=1, showImages=False, distortionCoeffsNumber=5)

Calibrate a single camera with a chessboard pattern.

Parameters:

• images (list or tuple) – A list (or tuple) of image paths, e.g. [“one.png”, “two.png”, …]

• chessboardSize (tuple) – Chessboard internal dimensions as (width, height). Dimensions should be different to avoid ambiguity. Default to (7,6).

• squareSize (float) – Length of the square side in the chosen world units. For example, if the square size is set in mm, measures in the 3D reconstruction will be in mm. Default to 1.

• showImages (bool) – If True, each processed image is showed to check for correct chessboard detection. Default to False.

• distortionCoeffsNumber (int, optional) – Number of distortion coefficients to be used for calibration, either either 0, 5 or 8. Coefficients are the same order as specified in OpenCV documentation. Please note that this library uses only a small subset of the advanced calibration options found in OpenCV. If set to 0 distortion correction is disabled (coefficients will be 0). Default to 5 (basic radial and tangential distortion correction).

Returns:

• retval (bool) – Same values of cv2.calibrateCamera.

• cameraMatrix (numpy.ndarray)

• distCoeffs (numpy.ndarray)

• rvecs (numpy.ndarray)

• tvecs (numpy.ndarray)

simplestereo.calibration.chessboardStereo(images, chessboardSize=(6, 7), squareSize=1, distortionCoeffsNumber=5)

Performs stereo calibration between two cameras and returns a StereoRig object.

First camera (generally left) will be put in world origin.

Parameters:

• images (list or tuple) – A list (or tuple) of 2 dimensional tuples (ordered left and right) of image paths, e.g. [(“oneL.png”,”oneR.png”), (“twoL.png”,”twoR.png”), …]

• chessboardSize (tuple) – Chessboard internal dimensions as (width, height). Dimensions should be different to avoid ambiguity. Default to (7,6).

• squareSize (float, optional) – Length of the square side in the chosen world units. For example, if the square size is set in mm, measures in the 3D reconstruction will be in mm. Default to 1.

• distortionCoeffsNumber (int, optional) – Number of distortion coefficients to be used for calibration, either 0, 5 or 8. Coefficients are the same order as specified in OpenCV documentation. Please note that this library uses only a small subset of the advanced calibration options found in OpenCV. If set to 0 distortion correction is disabled (coefficients will be 0). Default to 5 (basic radial and tangential distortion correction).

Returns:

• StereoRig – A StereoRig object

• ..todo:: – Iteratively exclude images that have high reprojection errors and re-calibrate.

simplestereo.calibration.generateChessboardSVG(chessboardSize, filepath, squareSize=20, border=10)

Write the desired chessboard to a SVG file.

chessboardSize is expressed as (columns, rows) tuple, counting internal line columns and rows as OpenCV does (e.g. to obtain a 10x7 chessboard, use (9,6)).

Parameters:

• chessboardSize (tuple) – Size of the chessboard as (columns, rows).

• filepath (string) – File path where to save the SVG file.

• squareSize (int) – Side of the square in millimeters. Default to 20. However it may not be represented exactly, depending on software.

simplestereo.calibration.getFundamentalMatrixFromProjections(P1, P2)

Compute the fundamental matrix from two projection matrices.

The algorithm is adapted from an original lesson of Cristina Turrini, UNIMI, Trento (09/04/2017).

Parameters:

• P1 (numpy.ndarray) – 3x4 camera projection matrices.

• P2 (numpy.ndarray) – 3x4 camera projection matrices.

Returns:

F – The 3x3 fundamental matrix.

Return type:

numpy.ndarray

simplestereo.calibration.phaseShift(periods, projectorResolution, cameraImages, chessboardSize=(6, 7), squareSize=1, camIntrinsic=None, camDistCoeffs=None)

Calibrate camera and projector using phase shifting and the heterodyne principle [Reich 1997].

Parameters:

• periods (list of lists) – Periods of fringe used in the projector as list of lists. First list is for the horizontal fringes, second for the vertical ones. In descending order (e.g. 1280, 1024, 512, …).

• projectorResolution (tuple) – Projector pixel resolution as (width, height).

• cameraImages (list or tuple) – A list of lists (one per set) of image paths acquired by the camera. Each set must be ordered, having 4 images for each period with horizontal followed by vertical images. In each set, last image is the one in normal light conditions. At least 5-6 sets are suggested.

• chessboardSize (tuple, optional) – Chessboard internal dimensions as (cols, rows). Dimensions should be different to avoid ambiguity. Default to (6,7).

• squareSize (float, optional) – If the square size is known, calibration can be in metric units. Default to 1.

• camIntrinsic (list, optional) – A 3x3 matrix representing camera intrinsic parameters. If not given it will be calculated.

• camIntrinsic – Camera distortion coefficients of 4, 5, 8, 12 or 14 elements (refer to OpenCV documentation). If not given they will be calculated.

Returns:

A StereoRig object

Return type:

StereoRig

simplestereo.calibration.phaseShiftWhite(periods, projectorResolution, cameraImages, chessboardSize=(6, 7), squareSize=1, camIntrinsic=None, camDistCoeffs=None, extended=False)

Calibrate camera and projector using phase shifting and heterodyne principle [Reich 1997]. Using center of white squares instead of corners as targets.

The center of a white square is well defined and less subject to noise or uncertanty of the phase value.

Parameters:

• periods (list of lists) – Periods of fringe used in the projector as list of lists. First list is for the horizontal fringes, second for the vertical ones. In descending order (e.g. 1280, 1024, 512, …).

• projectorResolution (tuple) – Projector pixel resolution as (width, height).

• cameraImages (list or tuple) – A list of lists (one per set) of image paths acquired by the camera. Each set must be ordered, having 4 images for each period with horizontal followed by vertical images. In each set, last image is the one in normal light conditions. At least 5-6 sets are suggested.

• chessboardSize (tuple, optional) – Chessboard internal dimensions as (cols, rows). Dimensions should be different to avoid ambiguity. Default to (6,7).

• squareSize (float, optional) – If the square size is known, calibration can be in metric units. Default to 1.

• camIntrinsic (list, optional) – A 3x3 matrix representing camera intrinsic parameters. If not given it will be calculated.

• camIntrinsic – Camera distortion coefficients of 4, 5, 8, 12 or 14 elements (refer to OpenCV documentation). If not given they will be calculated.

• extended (bool) – If True, perViewErrors of the stereo calibration are returned. Default to False.

Returns:

• StereoRig – A StereoRig object

• perViewErrors – Returned only if extended is True. For each pattern view, the RMS error of camera and projector is returned.

simplestereo.passive module

passive

Contains different passive stereo algorithms to build disparity maps.

Simpler algorithms, like StereoBM and StereoSGBM, are already implemented in OpenCV.

class simplestereo.passive.StereoASW(winSize=35, maxDisparity=16, minDisparity=0, gammaC=5, gammaP=17.5, consistent=False)

Bases: object

Custom implementation of “Adaptive Support-Weight Approach for Correspondence Search”, K. Yoon, I. Kweon, 2006.

Parameters:

• winSize (int) – Side of the square window. Must be an odd positive number. Default is 35.

• maxDisparity (int) – Maximum accepted disparity. Default is 16.

• minDisparity (int) – Minimum valid disparity, usually set to zero. Default is 0.

• gammaC (float) – Color parameter. If increased, it increases the color influence. Default is 5.

• gammaP (float) – Proximity parameter. If increased, it increases the proximity influence. Default is 17.5.

• consistent (bool) – If True consistent check is made, i.e. disparity is calculated first using left image as reference, then using right one as reference. Any non-corresponding value is invalidated (occluded) and assigned as the nearest minimum left-right non-occluded disparity. Original idea from occlusion detection and filling as in “Local stereo matching using geodesic support weights”, Asmaa Hosni et al., 2009. If enabled, running time is roughly doubled. Default to False.

Todo

Alternative version can be written like this: compute disparity map on every other pixel with the traditional algorithm, then fill the remaining pixels using left-right disparity boundaries. This proved to be 40-50% faster with no significant decrease in quality.

Warning

It gets very slow for high resolution images or with high winSize or maxDisparity values.

Note

This algorithm performs a 384x288 pixel image scan with maxDisparity=16 in less than 1 sec using 4 CPUs (while other implementations need 60 sec, see DOI 10.1007/s11554-012-0313-2 with code “yk”). To improve the final result, a smoothering filter could be applied.

Methods

compute(img1, img2)

Compute disparity map for BGR images.

compute(img1, img2)

Compute disparity map for BGR images.

Parameters:

• img1 (cv2.Mat) – A couple of OpenCV images (left and right, respectively) of same shape.

• img2 (cv2.Mat) – A couple of OpenCV images (left and right, respectively) of same shape.

Returns:

A disparity map of the same width and height of the images.

Return type:

numpy.ndarray (np.int16)

class simplestereo.passive.StereoGSW(winSize=11, maxDisparity=16, minDisparity=0, gamma=10, fMax=120, iterations=3, bins=20)

Bases: object

Incomplete implementation of “Local stereo matching using geodesic support weights”, Asmaa Hosni, Michael Bleyer, Margrit Gelautz and Christoph Rhemann (2009).

Parameters:

• winSize (int, optional) – Side of the square window. Must be an odd positive number.

• maxDisparity (int, optional) – Maximum accepted disparity. Default is 16.

• minDisparity (int, optional) – Minimum valid disparity, usually set to zero. Default is 0.

• gamma (int, optional) – Gamma parameter. If increased, it increases the geodesic weight influence. Default is 10.

• fMax (int or float, optional) – Color difference is capped to this value. Default is 120.

• iterations (int, optional) – Number of iteration for geodesic distances estimation. Default is 3.

• bins (int, optional) – Number of bins for histograms (currently not used, needed for Mutual Information). Default is 20.

• ..warning:: – Not optimized. Do not use in production.

• ..todo:: – This is a work in progress. The reference paper is not clear. Traditional Mutual Information computes a value for the whole window (not position based). However formula (5) suggests a per-pixel iteration. Currently implemented with sum of squared differences, weighted with geodesic. Need to implement Mutual information as matching cost. Need to implement right image consistency and subsequent occlusion filling.

Methods

compute(img1, img2)

Compute disparity map for 3-color channel images.

compute(img1, img2)

Compute disparity map for 3-color channel images.

simplestereo.points module

points

Functions to manage point clouds.

simplestereo.points.distortPoints(points, distCoeff)

Undistort relative coordinate points.

Parameters:

• points (list) – List of lists (or tuples) of x,y points in relative coordinates (already multiplied by the inverse intrinsic matrix and undistorted).

• distCoeff (list) – List of 4, 5 or 8 elements (see OpenCV).

Returns:

List of lists of distorted x,y points in relative coordinates

Return type:

list

Todo

To be extended for (k1,k2,p1,p2[,k3[,k4,k5,k6[,s1,s2,s3,s4[,τx,τy]]]]) vector of >8 elements. To use numpy.

simplestereo.points.exportPLY(points3D, filepath, referenceImage=None, precision=6)

Export raw point cloud to PLY file (ASCII).

Parameters:

• points3D (numpy.ndarray) – Array of 3D points. The last dimension must contain ordered x,y,z coordinates.

• filepath (str) – File path for the PLY file (absolute or relative).

• referenceImage (numpy.ndarray, optional) – Reference image to extract color from. It must contain the same number of points of points3D. Last dimension must be either 1 (grayscale) or 3 (BGR). Default to None.

• precision (int) – Decimal places to save coordinates with. Higher precision causes bigger file size. Default to 6.

simplestereo.points.getAdimensional3DPoints(disparityMap)

Get adimensional 3D points from the disparity map.

This is the adimensional version of RectifiedStereoRig.get3DPoints(). Useful to reconstruct non-metric 3D models from any disparity map when the stereo rig object is not known. It may lead to incorrect proportions.

Parameters:

disparityMap (numpy.ndarray) – A dense disparity map having same height and width of images.

Returns:

Array of points having shape (height,width,3), where at each y,x coordinates a (x,y,z) point is associated.

Return type:

numpy.ndarray

See also

simplestereo.RectifiedStereoRig.get3DPoints()

simplestereo.points.importPLY(filename, *properties)

Import 3D coordinates from PLY file.

Parameters:

• filename (str) – PLY file path.

• *properties (argument list, optional) – Property column positions to be extracted as float, in the same order. Default to (0,1,2).

Returns:

Array of data values with shape (number of values, number of properties).

Return type:

numpy.ndarray

Todo

Automatically read PLY properties as dict. Manage values other than float.

simplestereo.rectification module

rectification

Contains different rectification algorithms.

simplestereo.rectification.fusielloRectify(rig)

Computes the two rectifying homographies and returns a RectifiedStereoRig.

This method uses the algorithm illustrated in A compact algorithm for rectification of stereo pair, A. Fusiello et al., Machine Vision and Applications (2000).

Parameters:

rig (StereoRig) – An object of the StereoRig class. Camera must be position 1 (origin), projector in position 2.

Returns:

rectifiedStereoRigObj – An object of the RectifiedStereoRig class containing the rectifying homographies.

Return type:

RectifiedStereoRig

simplestereo.rectification.getBestXShearingTransformation(rectHomography, dims)

Get best shear transformation (affine) over x axis that minimizes distortion.

Applying a shearing transformation over the x axis does not affect rectification and allows to reduce image distortion. Original algorithm in par. 7 of Computying rectifying homographies for stereo vision, CVPR 1999, Loop C. and Zhang Z.

Parameters:

• rectHomography (numpy.ndarray) – A 3x3 rectification homography.

• dims (tuple) – Resolution of destination image as (width, height) tuple.

Returns:

S – A 3x3 shearing (x axis) transform.

Return type:

numpy.ndarray

Note

All the tranformations applied to the images must be taken into account when computing disparity for 3D reconstruction.

simplestereo.rectification.getFittingMatrix(intrinsicMatrix1, intrinsicMatrix2, H1, H2, dims1, dims2, distCoeffs1=None, distCoeffs2=None, destDims=None, alpha=1)

Compute affine tranformation to fit the rectified images into desidered dimensions.

After rectification usually the image is no more into the original image bounds. One can apply any transformation that do not affect disparity to fit the image into boundaries. This function corrects flipped images too. The algorithm may fail if one epipole is too close to the image.

Parameters:

• intrinsicMatrix1 (numpy.ndarray) – 3x3 original camera matrices of intrinsic parameters.

• intrinsicMatrix2 (numpy.ndarray) – 3x3 original camera matrices of intrinsic parameters.

• H1 (numpy.ndarray) – 3x3 rectifying homographies.

• H2 (numpy.ndarray) – 3x3 rectifying homographies.

• dims1 (tuple) – Resolution of images as (width, height) tuple.

• dims2 (tuple) – Resolution of images as (width, height) tuple.

• distCoeffs1 (numpy.ndarray, optional) – Distortion coefficients in the order followed by OpenCV. If None is passed, zero distortion is assumed.

• distCoeffs2 (numpy.ndarray, optional) – Distortion coefficients in the order followed by OpenCV. If None is passed, zero distortion is assumed.

• destDims (tuple, optional) – Resolution of destination images as (width, height) tuple (default to the first image resolution).

• alpha (float, optional) – Scaling parameter between 0 and 1 to be applied to both images. If alpha=1 (default), the corners of the original images are preserved. If alpha=0, only valid rectangle is made visible. Intermediate values produce a result in the middle. Extremely skewed camera positions do not work well with alpha<1.

Returns:

3x3 affine transformation to be used both for the first and for the second camera.

Return type:

numpy.ndarray

simplestereo.rectification.loopRectify(rig)

Computes the two rectifying homographies and returns a RectifiedStereoRig.

This method is an implementation of the algorithm illustrated in Computying rectifying homographies for stereo vision, CVPR 1999, Loop C. and Zhang Z. This function performs a minimization using scipy.optimize module.

Parameters:

rig (StereoRig) – An object of the StereoRig class.

Returns:

rectifiedStereoRigObj – An object of the RectifiedStereoRig class containing the rectifying homographies.

Return type:

RectifiedStereoRig

Note

Also an object of simplestereo.RectifiedStereoRig() may be passed as input to recalculate its rectification transformations (e.g. changing algorithm).

simplestereo.rectification.stereoRectify(rig)

Rectify the StereoRig object using the standard OpenCV algorithm.

This function computes the new common camera orientation by averaging. It does not produce the rectifying homographies with minimal perspective distortion.

Parameters:

rig (StereoRig) – An object of the StereoRig class

Returns:

rectifiedStereoRigObj – An object of the RectifiedStereoRig class containing the rectifying homographies.

Return type:

RectifiedStereoRig

simplestereo.unwrapping module

phaseUnwrapping

Contains different phase unwrapping strategies.

simplestereo.utils module

utils

This module provides general utilities.

class simplestereo.utils.Capture(device=0, flipY=False)

Bases: object

Capture a video stream continuously.

Allows to capture a video stream in a separate thread and grab the current frame when needed, minimizing lags for streaming and webcams. It supports webcams, URL streaming and video files.

Parameters:

• device (int or str) – Id of the opened video capturing device (i.e. a camera index). If there is a single camera connected, usually it will be 0 (default 0). Also the string containing full URL of the video stream (e.g. protocol://username:password@script?params) or a path to a video file.

• flipY (bool) – If True, output image is flipped on the Y-axis. Default to False.

Raises:

• ValueError – If device cannot be opened.

• .. note:: – When using video streaming URL the initialization may require some time. Check that the image frame is not None and / or insert a time.sleep() after object constructor.

Todo

Add support for other options (e.g. change focal length where supported).

Methods

get()	Retrieve the current frame.
getResolution()	Return current resolution as (width, height) tuple.
setFrameRate(fps)	Set framerate of the camera.
setResolution(width, height)	Set resolution of the camera.
start()	Start the capture in a separate thread.
stop()	Stop the capture.

get()

Retrieve the current frame.

Returns None if there is no frame (e.g. end of video file).

getResolution()

Return current resolution as (width, height) tuple.

setFrameRate(fps)

Set framerate of the camera.

Do not call this for video files or when the thread is running. It works only for supported cameras.

Parameters:

fps (int) – Frames per second.

Returns:

True if the framerate was set successfully, False otherwise.

Return type:

bool

setResolution(width, height)

Set resolution of the camera.

Do not call this for video files or when the thread is running. It works only for supported cameras.

Parameters:

• width (int) – Width and height to be set in pixels.

• heigth (int) – Width and height to be set in pixels.

Returns:

True if the resolution was set successfully, False otherwise.

Return type:

bool

start()

Start the capture in a separate thread.

No need to call this for video files. The thread continuously calls grab() to stay updated to the last frame, while retrieve() is called only when the frame is actually needed.

stop()

Stop the capture.

When finished, remember to call this method to stop the capturing thread. No need to call this for video files.

simplestereo.utils.drawCorrespondingEpipolarLines(img1, img2, F, x1=[], x2=[], color=(0, 0, 255), thickness=1)

Draw epipolar lines passing by given coordinates in img1 or img1.

The epipolar lines can be drawn on the images, knowing the fundamental matrix. Please note that this is an in-place method, i.e. passed images will be modified directly. Distortion is not taken into account.

Parameters:

• img1 (cv2.Mat) – A couple of OpenCV images taken with a stereo rig (ordered).

• img2 (cv2.Mat) – A couple of OpenCV images taken with a stereo rig (ordered).

• F (numpy.ndarray) – 3x3 fundamental matrix.

• x1 (list) – List of (x,y) coordinate points on the image 1 (or image 2, respectively).

• x2 (list) – List of (x,y) coordinate points on the image 1 (or image 2, respectively).

• color (tuple, optional) – Color as BGR tuple (default to (0,0,255) (red)).

• thickness (int, optional) – Thickness of the lines in pixels (default to 1).

Return type:

None

Note

This function needs undistorted images.

simplestereo.utils.getCrossProductMatrix(v)

Build the 3x3 antisymmetric matrix representing the cross product with v.

In literature this is often indicated as [v]_x.

Parameters:

v (numpy.ndarray or list) – A 3-dimensional vector.

Returns:

A 3x3 matrix representing the cross product with the input vector.

Return type:

numpy.ndarray

simplestereo.utils.moveExtrinsicOriginToFirstCamera(R1, R2, t1, t2)

Center extrinsic parameters world coordinate system into camera 1.

Compute R (rotation from camera 1 to camera 2) and T (translation from camera 1 to camera 2) as used in OpenCV from extrinsic of two cameras centered anywhere else. This is particularly useful when the world coordinate system is not centered into the first camera.

Parameters:

• R1 (np.array) – 3x3 rotation matrices that go from world origin to each camera center.

• R2 (np.array) – 3x3 rotation matrices that go from world origin to each camera center.

• t1 (np.array) – 3x1 translation vectors that go from world origin to each camera center.

• t2 (np.array) – 3x1 translation vectors that go from world origin to each camera center.

Returns:

• numpy.ndarray – Rotation matrix between the 1st and the 2nd camera coordinate systems as numpy.ndarray.

• numpy.ndarray – Translation vector between the coordinate systems of the cameras as numpy.ndarray.