2. API documentation

2.1. depthy.stereo

depthy.stereo.sad_block_matching(img_l: Optional[numpy.ndarray] = None, img_r: Optional[numpy.ndarray] = None, disp_max: int = 8, disp_min: int = 0, ws: int = 16, prec: float = 1.0, *args, **kwargs) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)

SAD (Sum of Absolute Differences) block matching variant.

Parameters

  • img_l – left image

  • img_r – right image

  • disp_max – maximum disparity

  • disp_min – minimum disparity

  • ws – window size of blocks

  • prec – precision for disparity (sub-pixel refinement if prec > 1)

Returns

tuple of two numpy arrays for left and right disparity maps

depthy.stereo.semi_global_matching(img_l: Optional[numpy.ndarray] = None, img_r: Optional[numpy.ndarray] = None, disp_max: int = 64, disp_min: int = 0, p1: float = 10, p2: float = 120, feat_method: str = 'census', dsim_method: str = 'xor', size_k: int = 3, blur_opt: bool = False, medi_opt: bool = False, *args, **kwargs) -> (<class 'numpy.ndarray'>, <class 'numpy.ndarray'>)

Semi-global matching variant covering feature extraction, dissimilarity measure and cost aggregation.

Parameters

  • img_l – left image

  • img_r – right image

  • disp_max – maximum disparity

  • disp_min – minimum disparity

  • p1 – minor penalty for cost aggregation

  • p2 – major penalty for cost aggregation

  • feat_method – feature extraction method (only supports ‘census’ or None)

  • dsim_method – dissimilarity measure (only supports ‘xor’ or ‘abs_diff’)

  • size_k – kernel width for filter operations

  • blur_opt – flag for Gaussian blur usage

  • medi_opt – flag for Median filter usage

Returns

tuple of two numpy arrays for left and right disparity maps

2.2. depthy.lightfield

depthy.lightfield.epi_depth(lf_img_arr: Optional[numpy.ndarray] = None, lf_wid: int = 1, primal_opt: bool = True, perc_clip: float = 1) → numpy.ndarray

High-level function for depth map computation based on epipolar images from a light-field.

Parameters

  • lf_img_arr – light-field image array with odd number of light-field dimensions

  • lf_wid – width of light-field rows and columns has to be an odd positive integer

  • primal_opt – flag for usage of primal dual algorithm

  • perc_clip – percentile for slope ratio extrema that will be clipped

Returns

disparity map

depthy.lightfield.extract_epi(lf_img_arr: Optional[numpy.ndarray] = None, spatial_idx: Optional[int] = None, angular_idx: Optional[int] = None, axis: bool = 0) → numpy.ndarray

Compose epipolar image from light-field array given the reference coordinates.

Parameters

  • lf_img_arr – light-field image array

  • spatial_idx – index for spatial image line (column or row)

  • angular_idx – index for light-field dimension (column or row)

  • axis – along vertical (False) or horizontal (True) direction

Returns

epipolar image as a copy of numpy array

depthy.lightfield.coherence_weighting()

Merge disparity maps using weights from the coherence as a reliability measure.

Parameters

  • disp_arr – stacked array of disparity maps

  • reli_arr – stacked array of coherence maps

Returns

weighted disparity, mean confidence

2.3. depthy.lightfield.structure_tensor

depthy.lightfield.structure_tensor.local_structure_tensor()

This function computes the local slopes of a given input image (e.g. epipolar image) using a structure tensor.

Parameters

  • img – image input (e.g. epipolar image)

  • si – sigma for inner Gaussian kernel

  • so – sigma for outer Gaussian kernel

  • slope_method – ‘eigen’ for eigendecomposition

  • grad_method – partial derivative method with ‘scharr’ as default and ‘sobel’ or ‘gradient’ as alternatives

  • f – focal length scaling local slope values

Returns

local_slopes, coherence, n

depthy.lightfield.structure_tensor.partial_img_gradients()

Compute partial derivatives of a 2-dimensional image.

Parameters

  • img – input image

  • method – method for first-order partial derivative featuring ‘scharr’, ‘sobel’ and ‘gradient’.

Returns

vertical partial gradient, horizontal partial gradient

2.4. depthy.misc.io_functions

depthy.misc.load_img_file(file_path: Optional[str] = None, norm_opt: bool = True) → numpy.ndarray

Load image file to numpy array.

Parameters

  • file_path – absolute path of file name

  • norm_opt – option to normalize intensity

Returns

image as numpy array

depthy.misc.load_lf_arr(fnames: Optional[Union[numpy.ndarray, list]] = None) → numpy.ndarray

Load light-field images from a list of file names (absolute path) in ascending order and reshape the array to equally sized views. Reshaping of light-field dimensions is based on \(\sqrt{N}\) where \(N\) is the total number of provided file names.

Parameters

fnames – list of file names (full absolute path)

Returns

numpy array of light-field images

2.5. depthy.misc.pfm_handler

depthy.misc.pfm_handler.save_pfm(img_arr: Optional[numpy.ndarray] = None, file_path: Optional[str] = None, scale: float = 1, norm: bool = False) → bool

Save a Numpy array to a PFM file. :param img_arr: image array :param file_path: file path string :param scale: scale value :param norm: normalization option :return: boolean

depthy.misc.pfm_handler.load_pfm(file_path: Optional[str] = None) → Union[numpy.ndarray, float]

Load a PFM file into a Numpy array. Note that it will have a shape of H x W, not W x H. Returns a tuple containing the loaded image and the scale factor from the file. :param file_path: file path to pgm file :return: grayscale image array, scale value

2.6. depthy.misc.ply_handler

depthy.misc.ply_handler.save_ply(pts: Optional[numpy.ndarray] = None, file_path: str = './depth.ply') → bool

Creates an ASCII text file containing a point cloud which is in line with the Polygon File Format (PLY). See https://en.wikipedia.org/wiki/PLY_(file_format) for further information.

Parameters

  • pts – numpy array [Zx6] carrying x,y,z as well as R,G,B information

  • file_path – file path string for file creation

Returns

True once saving succeeded

depthy.misc.ply_handler.disp2pts(disp_img: Optional[numpy.ndarray] = None, rgb_img: Optional[numpy.ndarray] = None, focal_length_mm: float = 1, focus_dist_mm: float = 200, baseline_mm: float = 1, sensor_mm: float = 1) → numpy.ndarray

Convert disparity image to an array of points representing the point cloud.

Parameters

  • disp_img – disparity image [MxN]

  • rgb_img – RGB image [MxNx3] which corresponds to disparity image, but is left optional

  • focal_length_mm – focal length in mm

  • focus_dist_mm – distance at which image is focused in mm

  • baseline_mm – spacing between optical centers of cameras in mm

  • sensor_mm – sensor size in mm

Returns

array of points [Zx6] where Z=M*N