Helpers

This module provides various helper functions.

get_default_config()

Return the default config.

get_default_debug_config()

Return the default logging config file.

get_boundaries(size_left, size_right, homo_left, homo_right)

Determine the boundaries of two transformed images.

When two images have been transformed by homographies to a ‘shared space’ (which holds both images), it’s possible that this ‘shared space’ is not aligned with the displayed area. Its possible that various points are outside of the display area. This function determines the max/min values of x and y of the both images in shared space in relation to the origin of the display area.

Example

             *--------*    *--------*
             |        |    |        |
             |  left  |    | right  |
             |        |    |        |
             *--------*    *--------*
                 \            /
       homo_left  \          / homo_right
                   \        /
                    v      v

shared space:      *--------*
      +~~~~~~~~~~~~|        |~~~~+
      ;  *--------*| right  |    ;
      ;  |        ||        |    ;
      ;  |  left  |*--------*    ;
      ;  |        |              ;
      ;  *--------* display_area ;
      +~~~~~~~~~~~~~~~~~~~~~~~~~~+

(In this example xmin would be the x value of the left border from the left image and ymin would be the y value of the top border from the right image)

Parameters:

• size_left (tuple) – Size (width, height) of the left image.
• size_right (tuple) – Size (width, height) of the right image.
• homo_left (ndarray) – An homography (3,3) which is used to transform the left image.
• homo_right (ndarray) – An homography (3,3) which is used to transform the right image.

Returns:

– xmin (float) – Minimal x value of both images after transformation. – ymin (float) – Minimal y value of both images after transformation. – xmax (float) – Maximal x value of both images after transformation. – ymax (float) – Maximal x value of both images after transformation.

get_transform_to_origin_mat(xmin, ymin)

Determine homography matrix to align ‘shared_space’ to display area origin.

Example

shared space:      *--------*
      +~~~~~~~~~~~~|        |~~~~+
      ;  *--------*| right  |    ;
      ;  |        ||        |    ;
      ;  |  left  |*--------*    ;
      ;  |        |              ;
      ;  *--------* display_area ;
      +~~~~~~~~~~~~~~~~~~~~~~~~~~+

                    |
                    | transformation to origin
                    V

      +~~~~~~~~~*--------*~~~~~~+
      ;         |        |      ;
      *--------*| right  |      ;
      |        ||        |      ;
      |  left  |*--------*      ;
      |        |                ;
      *--------* display_area   ;
      ;                         ;
      +~~~~~~~~~~~~~~~~~~~~~~~~~+

Parameters:

• xmin (float) – Minimal x value of images in ‘shared space’.
• ymin (float) – Minimal y value of images in ‘shared space’.

Returns:

(3,3) homography to align ‘shared space’ the to the origin of display area.

Return type:

ndarray

See also

• get_boundaries()

add_alpha_channel(image)

Add alpha channel to image for transparent areas.

Parameters:image (ndarray) – Image of shape (M,N) (black/white), (M,N,3) (BGR) or (M,N,4) already with alpha channel. Returns:image extended with alpha channel Return type:ndarray

form_rectangle(width, height)

Return a rectangle represented by 4 points ndarray (4,2).

The starting point is the Origin and the points are sorted in clockwise order.

Parameters:

• width (float) – Width of the rectangle.
• height (float) – Height of the rectangle.

Returns:

Rectangle represented by 4 points as ndarray (4,2).

Return type:

ndarray

sort_pts(points)

Sort points as convex quadrilateral.

Sort points in clockwise order, so that they form a convex quadrilateral.

Example

pts:                sorted_pts:
     x   x                      A---B
                  --->         /     \
   x       x                  D-------C

Parameters:points (ndarray) – Array of points (N,2). Returns:Clockwise ordered points (N,2), where the most up left point is the starting point. Return type:ndarray

raw_estimate_rect(points)

Abstract an rectangle from an convex quadrilateral.

The convex quadrilateral is defined by Points. The points must be sorted in clockwise order where the most up left point is the starting point. (see sort_pts)

Example

points:             rectangled points:
     A---B                    A'------B'
    /     \       --->        |       |
   D-------C                  D'------C'

The dimension of the rectangle is estimated in the following manner: |A'B'|=|D'C'|=max(|AB|,|DC|) and |A'D'|=|B'C'|=max(|AD|,|BC|)

Parameters:points (ndarray) – Array of clockwise ordered points (4,2), where most up left point is the starting point. Returns:‘Rectangled’ points (the rectangle is aligned to the origin). Return type:ndarray

harmonize_rects(rect_a, rect_b)

Harmonize two rectangles in their vertical dimension.

Example

rect_a:    rect_b:        harm_rect_a:       harm_rect_b:

             W-----X         A'--------------B'    W'----X'
 A-----B     |     |         |               |     |     |
 |     |     |     |   -->   |               |     |     |
 D-----C     |     |         |               |     |     |
             Z-----Y         D'--------------C'    Z'----Y'

Parameters:

• rect_a (ndarray) – Array of clockwise ordered points (4,2), where most up left point is the starting point.
• rect_b (ndarray) – Same as rect_a

Returns:

• harm_rect_a (ndarray) – Harmonized version of rect_a
• harm_rect_b (ndarray) – Harmonized version of rect_b

angles_to_points

Calculate point representations of angles.

The angle point representations points_reprs are calculated in dependency of the angle_center and the ray starting from this center, which is perpendicular to the right border. Positive angles will be interpreted as clockwise rotation.

Example

angle_center
      *--------x-Axis------>
       \         |
        \ angle /
         \     /
          \ --´
           \
points_repr *
             \
              v

Parameters:

• angle_centers (ndarray) – The centers of the angles. (N,2)
• angles (ndarray) – Angles in rad (length (N,)).
• distance (int) – The distance between the angle_centers and the point representations.

Returns:

• points_repr (ndarray) – Angles represented by points. (N,2)

See also

• points_to_angles()

points_to_angles(angle_centers, points_repr)

Convert angle point representation back to normal angle.

This function is the inverted version of angles_to_points().

Parameters:

• angle_centers (ndarray) – The centers of the angles. (N,2)
• points_repr (ndarray) – Angles represented by points. (N,2)

Returns:

Angles in rad (N,)

Return type:

ndarray

See also

• angles_to_points()

get_ratio_px_to_mm(start_point, end_point, distance_mm)

Return ratio between pixel and millimetre.

The function calculates the distance of two points (start_point, end_point) in pixels and then calculates ratio using the distance in pixels and the distance in mm distance_mm.

Parameters:

• start_point (ndarray) – Start point of the reference Line Segment (2,)
• end_point (ndarray) – End point of the reference Line Segment (2,)
• distance_mm (float) – The distance between the start_point and end_point of the line segment in real world in mm.

Returns:

The ratio between px and mm (the length of 1px in mm).

Return type:

float