API

Image

class pylapsy.image.Image(input=None, **meta)

pylapsy Image class

meta

dict-like object containing image meta information

Type:ImageMetaData

edit_log

dict-like object containing editing information

Type:CallableDict

Parameters:

• input – input image data (e.g. file path or numpy array)
• **meta – meta information

img

Image data array

Image data needs to be numpy array, either with 3 or 2 dimensions.

Raises:AttributeError – if no image data is assigned to this object

pyrlevel

Current pyramid level of image

shape

shape of image array

dtype

dtype of image array

is_gray

Boolean specifying wheter image is gray image.

is_color

Boolean specifying wheter image is color image.

file_path

Image file path

update_meta(**meta)

Update meta information

load_input(input, dtype=None)

Load input image data

duplicate()

Duplicate instance of this object

Returns:duplicated instance of this object Return type:Image

mean()

Mean value of image data

min()

Minimum values of image data

max()

Maximum value of image data

to_gray(inplace=True)

load_test_img()

Loads test image

add(val, inplace=True)

show(**kwargs)

Show image

save(path)

Save image to disk

Parameters:path (str) – path and filename of image

Image list

Created on Sun Sep 1 12:14:02 2019

@author: Jonas

class pylapsy.imagelist.ImageList(input)

Object representing a list of images

files

List with image file paths

filenames

totnum

Number of files in this list

index

Current index

current_img

Current image (at self._index)

next_image

Next image in list

load_input(input)

valid_index(index)

Check if input index is within range of images in the list

get_image(index)

Get image data

Meta data

class pylapsy.image_meta_data.ImageMetaData(*args, **kwargs)

Image metadata class

Extended dictionary that supports dynamic value generation (i.e. if an assigned value is callable, it will be executed on demand) and some other methods.

load(file_path)

Load meta information from file

Parameters:file_path (str) – image file containing meta information

Deshaker

class pylapsy.deshaker.Deshaker(imglist=None, outdir=None)

Interface for deshaking a series of images

imglist

List of images (instance of pylapsy.ImageList)

find_shifts(ref_index=None, parallel=True)

Find shifts for all images in imglist

Parameters:ref_index (int) – index of reference image in image list (shifts are computed wrt that image) Returns:dictionary containing shifts (dx, dy) and transformation matrices (matrices) for each image in imglist. Return type:dict

deshake(outdir=None, ref_index=None, sequence_id=None, save_preview_video=False, parallel=True)

Method that deshakes images sequence and saves result

Parameters:

• outdir (str, optional) – output directory. If None, a subdirectory will be created in the current directory
• ref_index (int, optional) – Index of reference image in sequence (all images are adjusted wrt to this image, defaults to 0).
• sequence_id (str, optional) – name of the sequence (for output directory)
• save_preview_video (bool) – if True, a preview video is saved (currently not working)

deshake_v0(outdir=None, ref_index=None, sequence_id=None, save_images=True, save_preview_video=True, preview_fps=24)

Method that deshakes images sequence and saves result

Parameters:

• outdir (str, optional) – output directory. If None, a subdirectory will be created in the current directory
• ref_index (int, optional) – Index of reference image in sequence (all images are adjusted wrt to this image, defaults to 0).
• sequence_id (str, optional) – name of the sequence (for output directory)
• save_images (bool) – if True, corrected images are saved
• save_preview_video (bool) – if True, a preview video is saved
• preview_fps (int) – fps of preview video (if applicable)

I/O

pylapsy.io.data_dir()

Basic data directory of pylapsy (containing example images)

pylapsy.io.get_testimg_files_deshake()

Get list of images for example deshake sequence

Returns:list with filepaths for example deshake sequence Return type:list

pylapsy.io.get_test_img(which=1)

Get file path of test image shipped with installation

Test images are stored in pylapsy/data dir and are named test_img<NUM>.jpg <NUM> can be specified via input parameter which.

Parameters:which (int) – number of test image Returns:image file location Return type:str Raises:FileNotFoundError – if installation data directory

pylapsy.io.find_image_files(dir_name=None, file_pattern=None, req_same_type=True)

Find image files in input directory

Parameters:

• dir_name (str, optional) – input directory, if None, current directory is used
• file_pattern (str) – glob style pattern, e.g. to specify file type (e.g. .jpg). If None, *. is used.
• req_same_type (bool) – if True and multiple file endings are found, then an exception is raised

Returns:

list with file paths

Return type:

list

Low-level utility methods

pylapsy.utils.imread(file_path)

Read image file using cv2.imread()

Note

opencv reads in BGR mode, not RGB

Parameters:file_path (str) – image file path Returns:image data Return type:ndarray

pylapsy.utils.imsave(img_arr, path)

Save image files using cv2.imwrite()

Parameters:

• img_arr (ndarray) – image data
• path (str) – destination of image

Returns:

success or not

Return type:

bool

pylapsy.utils.imshow(img_arr, add_cbar=False, cbar_label=None, cmap=None, ax=None, **kwargs)

Show image

Works both for grayscale and color images. For color images, it is assumed that the index is ordered in BGR, i.e. that the image was read using imread() (which uses cv2.imread()).

Parameters:

• img_arr (ndarray) – image data
• add_cbar (bool) – if True, a color bar is added to the figure
• cbar_label (str, optional) – label of colorbar (only relevant if add_cbar is True)
• cmap (str, optional) – colormap that is supposed to be used
• ax (axes) – matplotlib axes instance that is supposed to be used for display
• **kwargs – additional keyword args passed to imshow()

Returns:

Return type:

ax

pylapsy.utils.to_gray(img_arr)

Convert image array to gray

Parameters:img_arr (ndarray) – color image data with color indices in BGR mode (cf. imread()). Shape: (N, M, 3) Returns:img_arr – gray image data (cf. imread()). Shape: (N, M, 1) Return type:ndarray

pylapsy.utils.apply_sobel_hor(img_arr, **kwargs)

Horizontal sobel filter (wrapper for cv2.Sobel())

Parameters:

• img_arr (ndarray) – input grayscale image
• **kwargs – additional keyword args passed to cv2.Sobel()

Returns:

filtered input image array

Return type:

ndarray

pylapsy.utils.apply_sobel_vert(img_arr, **kwargs)

Vertical sobel filter (wrapper for cv2.Sobel())

Parameters:

• img_arr (ndarray) – input grayscale image
• **kwargs – additional keyword args passed to cv2.Sobel()

Returns:

filtered input image array

Return type:

ndarray

pylapsy.utils.apply_sobel_2d(img_arr, **kwargs)

Apply 2D sobel filter to in input gray-image

Combines output of apply_sobel_hor() and apply_sobel_vert() using cv2.bitwise_or() to retrieve edges in all directions.

Parameters:

• img_arr (ndarray) – input grayscale image
• **kwargs – additional keyword args passed to cv2.Sobel()

Returns:

filtered input image array

Return type:

ndarray

pylapsy.utils.find_good_features_to_track(img_arr, plot=False, **params)

Wrapper for cv2.goodFeaturesToTrack()

See here for more information.

Parameters:

• img_arr (ndarray) – image data from suitable tracking coordinates are supposed to be identified
• plot (bool) – option that plots the detected points onto the input image
• **params – additional input parameters that are passed to cv2.goodFeaturesToTrack()

Returns:

list of coordinates

Return type:

ndarray

pylapsy.utils.plot_feature_points(points, ax, marker='+', markersize=20, color='r', mew=3)

Plot feature points into image

Parameters:

• points (ndarray) – feature points either retrieved using find_good_features_to_track() or compute_flow_lk()
• ax (axes) – matplotlib axes instance in which the points are supposed to be plotted (e.g. output of imshow())
• marker (str) – marker that is supposed to be used to plot the points
• markersize (int) – size of markers
• color (str) – color of points
• mew (int) – marker edge width

Returns:

Return type:

ax

pylapsy.utils.compute_flow_lk(img1, img2, points_to_track=None, **params)

Method that computes optical flow using Lucas-Kanade algorithm

Parameters:

• img1 (ndarray) – first image
• img2 (ndarray) – next image
• points_to_track (ndarray, optional) – feature points that are used for tracking (e.g. output of find_good_features_to_track()). Uses find_good_features_to_track(), if unspecified.
• **params – additional keyword args passed to cv2.calcOpticalFlowPyrLK()

Returns:

• ndarray – feature points in img1 that could be used for successful tracking (corresponds to points_to_track)
• ndarray – same points as found in level 2

pylapsy.utils.find_affine_partial2d(p0=None, p1=None, **kwargs)

Find 2D affine transformation matrix

Find affine transformation matrix for translation and rotation based on input coordinates. Wrapper for method cv2.estimateAffinePartial2D().

Note

Input feature points p0 and p1 can be retrieved from 2 images using method compute_flow_lk().

Parameters:

• p0 (ndarray) – coordinates of feature points in first image
• p1 (ndarrax) – coordinates of feature points in next image
• **kwargs – additional keyword args passed to cv2.estimateAffinePartial2D()

Returns:

transformation matrix

Return type:

ndarray

pylapsy.utils.find_homography(p0=None, p1=None)

Find homography matrix

Find homography matrix based on input coordinates. Wrapper for method cv2.estimateAffinePartial2D().

Note

Input feature points p0 and p1 can be retrieved from 2 images using method compute_flow_lk().

Parameters:

• p0 (ndarray) – coordinates of feature points in first image
• p1 (ndarrax) – coordinates of feature points in next image
• **kwargs – additional keyword args passed to cv2.estimateAffinePartial2D()

Returns:

transformation matrix

Return type:

ndarray

pylapsy.utils.find_shift(first_gray, second_gray, **feature_lk_params)

Find shift between two input images using lukas kanade optical flow

Detects shift at suitable points to track in both images (e.g. corners) and based on detected shifts, finds the affine transformation that can be used to shift and rotate the second image such that it matches best the first image

Parameters:

• first_gray (ndarray) – first image (gray scale)
• second_gray (ndarray) – second image
• **feature_lk_params – additional, optional input keyword args passed to compute_flow_lk(). Default settings for lukas kanade can be found in defaults

Returns:

• tuple – (dx, dy) shift
• float – rotation angle
• ndarray – affine transformation matrix

pylapsy.utils.shift_image(img_arr, m=None)

pylapsy.utils.crop_shift(img, shift, cv=True)

pylapsy.utils.to_pylapsy_image(input)

Convert input to instance of pylapsy.Image class

Accepts valid image file path or numpy array

pylapsy.utils.get_crop(dx, dy, w0, h0)

Get crop ROI based on shift (dx, dy) and original image size

dx : float or ndarray

x shift or list of x shifts (for batch processing)

dy : float or ndarray

y shift or list of y shifts

w0 : int

original image width

h0 : int

original image height

Returns:4-element tuple containing ROI: (x0, x1, y0, y1) Return type:tuple

pylapsy.utils.deshake(img1, img2, crop=False)

High level scripts

pylapsy.highlevel_methods.deshake(dir_name=None, file_pattern=None, outdir=None, **deshake_args)

Deshake image sequence

Applies deshaking to all images (which should be part of a timelapse sequence) and saves the corrected images in provided output directory. By default, also a preview video is created. For details see Deshaker.

Parameters:

• dir_name (str, optional) – Image directory. If None, the current directory is used. The default is None.
• file_pattern (str, optional) – Pattern used to identify images in the input directory (e.g. *.jpg). The default is None.
• outdir (str, optional) – Output. The default is None.
• **deshake_args – Additional keyword args passed to Deshaker.deshake()

CLI

Command line interface of timelapsy

usage: ply [-h] [-d DIR] [-o OUTDIR] [--file_pattern FILE_PATTERN] task

Positional Arguments

task	Processing task that is supposed to be performed. Choose from: [‘deshake’, ‘info’]

Named Arguments

-d, --dir	Input directory containing timelapse sequence. Uses “.” if unspecified Default: “.”
-o, --outdir	Output directory for processed data. If unspecified a subdirectory “pylapsy_out” is created in current directory.
--file_pattern	Filename pattern used to identify image files (e.g. *.jpg) Default: “*”