Core modules¶

Core image processing functions. Any function can be executed in manual mode (python code) or interactive mode (yaml files). In general, the typical order in which the different steps are performed is something like:

preprocessing > segmentation > measurement > visualization > export

However, since phenopype version 2 you can arrange them however you like.

Preprocessing¶

phenopype.core.preprocessing.blur(image, kernel_size=5, method='averaging', sigma_color=75, sigma_space=75, verbose=False, custom_kernel=None, **kwargs)¶

Apply a blurring algorithm to an image with enhanced features.

Parameters:

image (ndarray) – The input image.
kernel_size (int, optional) – Size of the blurring kernel, must be positive and odd.
method (str, optional) – Blurring algorithm: ‘averaging’, ‘gaussian’, ‘median’, ‘bilateral’, or ‘custom’.
sigma_color (int, optional) – For ‘bilateral’ filter, the filter sigma in the color space.
sigma_space (int, optional) – For ‘bilateral’ filter, the filter sigma in the coordinate space.
verbose (bool, optional) – If True, prints additional details about the process.
custom_kernel (ndarray, optional) – Custom kernel for convolution if method is ‘custom’.

Returns:

The blurred image.

Return type:

ndarray

phenopype.core.preprocessing.clip_histogram(image, percent=1)¶

Enhances the contrast of an image by clipping the histogram and applying histogram stretching.

Parameters:

image (ndarray) – The input grayscale image.
percent (float, optional) – The percentage of the histogram to be clipped from both tails. Default is 1%.

Returns:

image – The contrast-enhanced image.

Return type:

ndarray

phenopype.core.preprocessing.create_mask(image, tool='rectangle', include=True, label=None, line_colour='default', line_width='auto', label_colour='default', label_size='auto', label_width='auto', **kwargs)¶

Mask an area by drawing a rectangle or polygon. Multiple mask components count as the same mask - e.g., if objects that you would like to mask out or include can be scattered across the image. Rectangles will finish upon lifting the mouse button, polygons are completed by pressing CTRL.

ANNOTATION FUNCTION

Parameters:

image (array) – input image
tool ({"rectangle","polygon"} str, optional) – Type of mask tool to be used. The default is “rectangle”.
include (bool, optional) – include or exclude area inside mask
label (str, optional) – label string for this mask and all its components
line_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour line colour - default colour as specified in settings
line_width ({"auto", ... int > 0} int, optional) – contour line width - automatically scaled to image by default
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour label colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – contour label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – contour label font thickness - automatically scaled to image by default

Returns:

annotations – phenopype annotation containing mask coordinates

Return type:

dict

phenopype.core.preprocessing.detect_mask(image, include=True, label=None, shape='circle', resize=1, circle_args={'dp': 1, 'max_radius': 0, 'min_dist': 50, 'min_radius': 0, 'param1': 200, 'param2': 100}, **kwargs)¶

Detects geometric shapes in a single channel image (currently only circles are implemented) and converts boundary contours to a mask to include or exclude parts of the image. Depending on the object type, different settings apply.

Parameters:

image (ndarray) – input image (single channel).
include (bool, optional) – should the resulting mask include or exclude areas. The default is True.
shape (str, optional) – which geometric shape to be detected. The default is “circle”.
resize ((0.1-1) float, optional) – resize factor for image (some shape detection algorithms are slow if the image is very large). The default is 1.
circle_args (dict, optional) –
A set of options for circle detection (for details see https://docs.opencv.org/3.4.9/dd/d1a/group__imgproc__feature.html ):
- dp: inverse ratio of the accumulator resolution to the image ressolution
- min_dist: minimum distance between the centers of the detected circles
- param1: higher threshold passed to the canny-edge detector
- param2: accumulator threshold - smaller = more false positives
- min_radius: minimum circle radius
- max_radius: maximum circle radius
The default is:
```
{
    "dp":1,
     "min_dist":50,
     "param1":200,
     "param2":100,
     "min_radius":0,
     "max_radius":0
     }
```

Returns:

annotations – phenopype annotation

Return type:

dict

phenopype.core.preprocessing.create_reference(image, unit='mm', line_colour='default', line_width='auto', label=True, label_colour='default', label_size='auto', label_width='auto', mask=False, **kwargs)¶

Measure a size or colour reference card. Minimum input interaction is measuring a size reference: click on two points inside the provided image, and enter the distance - returns the pixel-to-mm-ratio.

In an optional second step, drag a rectangle mask over the reference card to exclude it from anysubsequent image segementation. The mask can also be stored as a template for automatic reference detection with the “detect_reference” function.

Parameters:

image (ndarray) – input image
mask (bool, optional) – mask a reference card inside the image and return its coordinates as
line_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour line colour - default colour as specified in settings
line_width ({"auto", ... int > 0} int, optional) – contour line width - automatically scaled to image by default
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour label colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – contour label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – contour label font thickness - automatically scaled to image by default

Returns:

annotations – phenopype annotation

Return type:

dict

phenopype.core.preprocessing.detect_reference(image, template, px_ratio, unit, template_id='a', get_mask=True, manual_fallback=True, correct_colours=False, min_matches=10, resize=1, **kwargs)¶

Find reference from a template created with “create_reference”. Image registration is run by the “AKAZE” algorithm. Future implementations will include more algorithms to select from. First, use “create_reference” with “mask=True” and pass the template to this function. This happends automatically in the low and high throughput workflow. Use “equalize=True” to adjust the histograms of all colour channels to the reference image.

AKAZE: http://www.bmva.org/bmvc/2013/Papers/paper0013/abstract0013.pdf

Parameters:

image (ndarray) – input image
template (array) – template image-crop containing reference card
px_ratio – px-mm-ratio of template image
get_mask (bool) – retrieve mask and create annotation. The default is True.
manual_fallback (bool) – use manual reference-tool in case detection fails. The default is True.
correct_colours (bool, optional) – should the provided image be colour corrected to match the template images’ histogram
min_matches (int, optional) – minimum key point matches for image registration
resize (num, optional) – resize image to speed up detection process. default: 0.5 for images with diameter > 5000px (WARNING: too low values may result in poor detection performance or even crashes)

Returns:

annotations – phenopype annotation

Return type:

dict

phenopype.core.preprocessing.detect_QRcode(image, rot_steps=10, preprocess=True, rotate=True, max_dim=1000, enter_manually=False, label='ID', label_colour='default', label_size='auto', label_width='auto', **kwargs)¶

Find and read out a QR code that is contained inside an image. Rotate image until code is detected, or enter code manually if detection fails.

Parameters:

image (ndarray) – input image
rot_steps (int, optional) – angle by which image is rotated (until 360 is reached). The default is 20.
enter_manually (bool, optional) – enter code manually if detection fails. The default is False.
show_results (bool, optional) – show the detection results. The default is False.
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – text colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – text label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – text label font thickness - automatically scaled to image by default

Returns:

annotations – phenopype annotation

Return type:

dict

phenopype.core.preprocessing.decompose_image(image, channel='gray', invert=False, **kwargs)¶

Extract single channel from multi-channel array.

Parameters:

image (ndarray) – input image
channel ({"raw", "gray", "red", "green", "blue", "hue", "saturation", "value"} str, optional) – select specific image channel
invert (false, bool) – invert all pixel intensities in image (e.g. 0 to 255 or 100 to 155)

Returns:

image – decomposed image.

Return type:

ndarray

phenopype.core.preprocessing.write_comment(image, label='ID', label_colour='default', label_size='auto', label_width='auto', **kwargs)¶

Add a comment.

Parameters:

image (ndarray) – input image
field (str, optional) – name the comment-field (useful for later processing). The default is “ID”.

Returns:

annotation_ref – phenopype annotation containing comment

Return type:

dict

Segmentation¶

phenopype.core.segmentation.contour_to_mask(annotations, include=True, label=None, box_margin=0, largest=True, **kwargs)¶

Converts a contour to a mask annotation, e.g. for the purpose of creating an ROI and exporting it or for subsequent segmentation inside that mask. Creates a rectangle bounding box around the largest or all contours.

Parameters:

annotation (dict) – phenopype annotation containing contours
include (bool, optional) – include or exclude area inside mask
label (str, optional) – text label for this mask and all its components
box_margin (int, optional) – margin that is added between the outer perimeter of the contour and the box
largest (bool, optional) – either use only the largest contour or concatenate all supplied contours

Returns:

annotation – phenopype annotation containing contours

Return type:

dict

phenopype.core.segmentation.detect_contour(image, approximation='simple', retrieval='ext', match_against=None, apply_drawing=False, offset_coords=[0, 0], stats_mode='circle', min_nodes=3, max_nodes=inf, min_area=0, max_area=inf, min_diameter=0, max_diameter=inf, **kwargs)¶

Find objects in binarized image. The input image needs to be a binarized image A flavor of different approximation algorithms and retrieval intstructions can be applied. The contours can also be filtered for minimum area, diameter or nodes (= number of corners).

Parameters:

image (ndarray) – input image (binary)
approximation ({"none", "simple", "L1", "KCOS"] str, optional) –
contour approximation algorithm:
- none: no approximation, all contour coordinates are returned
- simple: only the minimum coordinates required are returned
- L1: Teh-Chin chain approximation algorithm
- KCOS: Teh-Chin chain approximation algorithm
retrieval ({"ext", "list", "tree", "ccomp", "flood"} str, optional) –
contour retrieval procedure:
- ext: retrieves only the extreme outer contours
- list: retrieves all of the contours without establishing any hierarchical relationships
- tree: retrieves all of the contours and reconstructs a full hierarchy of nested contours
- ccomp: retrieves all of the contours and organizes them into a two-level hierarchy (parent and child)
- flood: flood-fill algorithm
offset_coords (tuple, optional) – offset by which every contour point is shifted.
min_nodes (int, optional) – minimum number of coordinates
max_nodes (int, optional) – maximum number of coordinates
min_area (int, optional) – minimum contour area in pixels
max_area (int, optional) – maximum contour area in pixels
min_diameter (int, optional) – minimum diameter of boundary circle
max_diameter (int, optional) – maximum diameter of boundary circle

Returns:

annotation – phenopype annotation containing contours

Return type:

dict

phenopype.core.segmentation.edit_contour(image, annotations, line_width='auto', overlay_blend=0.2, overlay_colour_left='default', overlay_colour_right='default', **kwargs)¶

Edit contours with a “paintbrush”. The brush size can be controlled by pressing Tab and using the mousewhell. Right-click removes, and left-click adds areas to contours. Overlay colour, transparency (blend) and outline can be controlled.

Parameters:

image (ndarray) – input image
annotations (dict) – phenopype annotation containing contours
overlay_blend (float, optional) – transparency / colour-mixing of the contour overlay
line_width (int, optional) – add outline to the contours. useful when overlay_blend == 0
left_colour (str, optional) – overlay colour for left click (include). (for options see pp.colour)
right_colour (str, optional) – overlay colour for right click (exclude). (for options see pp.colour)

Returns:

annotations – phenopype annotation containing contours

Return type:

dict

phenopype.core.segmentation.mask_to_contour(annotations, include=True, box_margin=0, **kwargs)¶

Converts a mask to contour annotation, e.g. for the purpose of extracting information from this mask.

Parameters:

annotation (dict) – phenopype annotation containing masks
include (bool, optional) – include or exclude area inside contour
box_margin (int, optional) – margin that is added between the outer perimeter of the mask and the box

Returns:

annotation – phenopype annotation containing contours

Return type:

dict

phenopype.core.segmentation.morphology(image, kernel_size=5, shape='rect', operation='close', iterations=1, **kwargs)¶

Performs advanced morphological transformations using erosion and dilation as basic operations. Provides different kernel shapes and a suite of operation types (read more about morphological operations here: https://docs.opencv.org/master/db/df6/tutorial_erosion_dilatation.html)

Parameters:

image (ndarray) – input image (binary)
kernel_size (int, optional) – size of the morphology kernel (has to be odd - even numbers will be ceiled)
shape ({"rect", "cross", "ellipse"} str, optional) – shape of the kernel
operation ({erode, dilate, open, close, gradient, tophat, blackhat, hitmiss} str, optional) –
the morphology operation to be performed:
- erode: remove pixels from the border
- dilate: add pixels to the border
- open: erosion followed by dilation
- close: dilation followed by erosion
- gradient: difference between dilation and erosion of an input image
- tophat: difference between input image and opening of input image
- blackhat: difference between input image and closing of input image
- hitmiss: find patterns in binary images (read more here: https://docs.opencv.org/master/db/d06/tutorial_hitOrMiss.html)
iterations (int, optional) – number of times to run morphology operation

Returns:

image – processed binary image

Return type:

ndarray

phenopype.core.segmentation.threshold(image, method='otsu', constant=1, blocksize=99, value=127, channel=None, mask=True, invert=False, **kwargs)¶

Applies a threshold to create a binary image from a grayscale or a multichannel image (see phenopype.core.preprocessing.decompose_image for channel options).

Three types of thresholding algorithms are supported:

otsu: use Otsu algorithm to choose the optimal threshold value
adaptive: dynamic threshold values across image (uses arguments “blocksize” and “constant”)
binary: fixed threshold value (uses argument “value”)

Mask annotations can be supplied to include or exclude areas.

Parameters:

image (ndarray) – input image
method ({"otsu", "adaptive", "binary"} str, optional) – type of thresholding algorithm to be used
blocksize (int, optional) – Size of a pixel neighborhood that is used to calculate a threshold value for the pixel (has to be odd - even numbers will be ceiled; for “adaptive” method)
constant (int, optional) – value to subtract from binarization output (for “adaptive” method)
value ({between 0 and 255} int, optional) – thesholding value (for “binary” method)
{"gray" (channel) – which channel of the image to use for thresholding
"red" (str, optional) – which channel of the image to use for thresholding
"green" (str, optional) – which channel of the image to use for thresholding
"blue"} (str, optional) – which channel of the image to use for thresholding

Returns:

image – binary image

Return type:

ndarray

phenopype.core.segmentation.watershed(image, annotations, iterations=1, kernel_size=3, distance_cutoff=0.8, distance_mask=0, distance_type='l1', **kwargs)¶

Performs non-parametric marker-based segmentation - useful if many detected contours are touching or overlapping with each other. Input image should be a binary image that serves as the true background. Iteratively, edges are eroded, the difference serves as markers.

Parameters:

image (ndarray) – input image
image_thresh (array) – binary image (e.g. from threshold)
kernel_size (int, optional) – size of the diff-kernel (has to be odd - even numbers will be ceiled)
iterations (int, optional) – number of times to apply diff-operation
distance_cutoff ({between 0 and 1} float, optional) – watershed distance transform cutoff (larger values discard more pixels)
distance_mask ({0, 3, 5} int, optional) – size of distance mask - not all sizes work with all distance types (will be coerced to 0)
distance_type ({"user", "l1", "l2", "C", "l12", "fair", "welsch", "huber"} str, optional) – distance transformation type

Returns:

image – binary image

Return type:

ndarray

Measurement¶

phenopype.core.measurement.set_landmark(image, point_colour='default', point_size='auto', label=True, label_colour='default', label_size='auto', label_width='auto', **kwargs)¶

Place landmarks. Note that modifying the appearance of the points will only be effective for the placement, not for subsequent drawing, visualization, and export.

Parameters:

image (ndarray) – input image
point_colour (str, optional) – landmark point colour (for options see pp.colour)
point_size (int, optional) – landmark point size in pixels
label (bool, optional) – add text label
label_colour (str, optional) – landmark label colour (for options see pp.colour)
label_size (int, optional) – landmark label font size (scaled to image)
label_width (int, optional) – landmark label font width (scaled to image)

Returns:

annotations – phenopype annotation containing landmarks

Return type:

dict

phenopype.core.measurement.set_polyline(image, line_width='auto', line_colour='default', **kwargs)¶

Set points, draw a connected line between them, and measure its length. Note that modifying the appearance of the lines will only be effective for the placement, not for subsequent drawing, visualization, and export.

Parameters:

image (ndarray) – input image
line_width (int, optional) – width of polyline
line_colour (str, optional) – poly line colour (for options see pp.colour)

Returns:

annotations – phenopype annotation containing polylines

Return type:

dict

phenopype.core.measurement.detect_skeleton(annotations, thinning='zhangsuen', **kwargs)¶

Applies a binary blob thinning operation, to achieve a skeletization of the input image using the technique, i.e. retrieve the topological skeleton (https://en.wikipedia.org/wiki/Topological_skeleton), using the algorithms of Thang-Suen or Guo-Hall.

Parameters:

image (ndarray) – input image
annotation (dict) – phenopype annotation containing contours
thinning ({"zhangsuen", "guohall"} str, optional) – type of thinning algorithm to apply

Returns:

annotations – phenopype annotation containing skeleton coords

Return type:

dict

phenopype.core.measurement.compute_shape_features(annotations, features=['basic'], min_diameter=5, **kwargs)¶

Collects a set of 41 shape descriptors from every contour. There are three sets of descriptors: basic shape descriptors, moments, and hu moments. Two additional features, contour area and diameter are already provided by the find_contours function. https://docs.opencv.org/3.4.9/d3/dc0/group__imgproc__shape.html

Of the basic shape descriptors, all 12 are translational invariants, 8 are rotation invariant (rect_height and rect_width are not) and 4 are also scale invariant (circularity, compactness, roundness, solidity). https://en.wikipedia.org/wiki/Shape_factor_(image_analysis_and_microscopy)

The moments set encompasses 10 raw spatial moments (some are translation and rotation invariants, but not all), 7 central moments (all translational invariant) and 7 central normalized moments (all translational and scale invariant). https://en.wikipedia.org/wiki/Image_moment

The 7 hu moments are derived of the central moments, and are all translation, scale and rotation invariant. http://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Hu.pdf

Basic shape descriptors:

circularity = 4 * np.pi * contour_area / contour_perimeter_length^2
compactness = √(4 * contour_area / pi) / contour_diameter
min_rect_max = minimum bounding rectangle major axis
min_rect_min = minimum bounding rectangle minor axis
perimeter_length = total length of contour perimenter
rect_height = height of the bounding rectangle (“caliper dim 1”)
rect_width = width of the bounding rectangle (“caliper dim 2”)
roundness = (4 * contour_area) / (pi * contour_perimeter_length^2)
solidity = contour_area / convex_hull_area
tri_area = area of minimum bounding triangle

Moments:

raw moments = m00, m10, m01, m20, m11, m02, m30, m21, m12, m03
central moments = mu20, mu11, mu02, mu30, mu21, mu12, mu03,
normalized central moments = nu20, nu11, nu02, nu30, nu21, nu12, nu03

Hu moments:

hu moments:: hu1 - hu7

Parameters:

image (ndarray) – input image
features (["basic", "moments", "hu_moments"]) – type of shape features to extract

Returns:

annotations – phenopype annotation containing shape features

Return type:

dict

phenopype.core.measurement.compute_texture_features(image, annotations, features=['firstorder'], channel_names=['blue', 'green', 'red'], min_diameter=5, **kwargs)¶

Collects 120 texture features using the pyradiomics feature extractor ( https://pyradiomics.readthedocs.io/en/latest/features.html ):

firstorder: First Order Statistics (19 features)
shape2d: Shape-based (2D) (16 features)
glcm: Gray Level Cooccurence Matrix (24 features)
gldm: Gray Level Dependence Matrix (14 features)
glrm: Gray Level Run Length Matrix (16 features)
glszm: Gray Level Size Zone Matrix (16 features)
ngtdm: Neighbouring Gray Tone Difference Matrix (5 features)

Features are collected from every contour that is supplied along with the raw image, which, depending on the number of contours, may result in long computing time and very large dataframes.

The specified channels correspond to the channels that can be selected in phenopype.core.preprocessing.decompose_image.

Parameters:

image (ndarray) – input image
annotation (dict) – phenopype annotation containing contours
features (["firstorder", "shape", "glcm", "gldm", "glrlm", "glszm", "ngtdm"] list, optional) – type of texture features to extract
channels (list, optional) – image channel to extract texture features from. if none is given, will extract from all channels in image
min_diameter (int, optional) – minimum diameter of the contour (shouldn’t be too small for sensible feature extraction’)

Returns:

annotations – phenopype annotation containing texture features

Return type:

dict

Visualization¶

phenopype.core.visualization.draw_comment(image, annotations, label_colour='default', label_size='auto', label_width='auto', background=True, background_colour='white', background_pad=10, background_border='black', font='simplex', **kwargs)¶

Parameters:

image (ndarray) – image used as canvas
annotation (dict) – phenopype annotation containing QR-code (comment)
line_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour line colour - default colour as specified in settings
line_width ({"auto", ... int > 0} int, optional) – contour line width - automatically scaled to image by default
label (bool, optional) – draw reference label
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour label colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – contour label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – contour label font thickness - automatically scaled to image by default
**kwargs (TYPE) – DESCRIPTION.

Returns:

image – canvas with contours

Return type:

ndarray

phenopype.core.visualization.draw_contour(image, annotations, fill=0.3, line_colour='default', line_width='auto', label=False, label_colour='default', label_size='auto', label_width='auto', offset_coords=None, bbox=False, bbox_ext=20, bbox_colour='default', bbox_line_width='auto', **kwargs)¶

Draw contours and their labels onto a canvas. Can be filled or empty, offset coordinates can be supplied.

Parameters:

image (ndarray) – image used as canvas
annotation (dict) – phenopype annotation containing contours
offset_coords (tuple, optional) – offset coordinates, will be added to all contours
label (bool, optional) – draw contour label
fill (float, optional) – background transparency for contour fill (0=no fill).
level (int, optional) – the default is 3.
line_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour line colour - default colour as specified in settings
line_width ({"auto", ... int > 0} int, optional) – contour line width - automatically scaled to image by default
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour label colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – contour label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – contour label font thickness - automatically scaled to image by default
bounding_box (bool, optional) – draw bounding box around the contour
bounding_box_ext (in, optional) – value in pixels by which the bounding box should be extended
bounding_box_colour ({"green", "red", "blue", "black", "white"} str, optional) – bounding box line colour
bounding_box_line_width (int, optional) – bounding box line width

Returns:

image – canvas with contours

Return type:

ndarray

phenopype.core.visualization.draw_landmark(image, annotations, label=True, label_colour='default', label_size='auto', label_width='auto', offset=0, point_colour='default', point_size='auto', **kwargs)¶

Draw landmarks into an image.

Parameters:

image (ndarray) – image used as canvas
annotation (dict) – phenopype annotation containing landmarks
label (bool, optional) – draw landmark label
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour label colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – contour label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – contour label font thickness - automatically scaled to image by default
offset (int, optional) – add offset (in pixels) to text location (to bottom-left corner of the text string)
point_colour ({"green", "red", "blue", "black", "white"} str, optional) – landmark point colour
point_size (int, optional) – landmark point size in pixels

Returns:

image – canvas with landmarks

Return type:

ndarray

phenopype.core.visualization.draw_mask(image, annotations, line_colour='default', line_width='auto', fill=0, label=False, label_colour='default', label_size='auto', label_width='auto', **kwargs)¶

Draw masks into an image. This function is also used to draw the perimeter of a created or detected reference card.

Parameters:

image (ndarray) – image used as canvas
annotation (dict) – phenopype annotation containing masks
label (bool, optional) – draw mask label
line_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour line colour - default colour as specified in settings
line_width ({"auto", ... int > 0} int, optional) – contour line width - automatically scaled to image by default
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour label colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – contour label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – contour label font thickness - automatically scaled to image by default

Returns:

image – canvas with masks

Return type:

ndarray

phenopype.core.visualization.draw_polyline(image, annotations, line_colour='default', line_width='auto', show_nodes=False, node_colour='default', node_size='auto', **kwargs)¶

Draw masks into an image. This function is also used to draw the perimeter of a created or detected reference card.

Parameters:

image (ndarray) – image used as canvas
annotation (dict) – phenopype annotation containing lines
line_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour line colour - default colour as specified in settings
line_width ({"auto", ... int > 0} int, optional) – contour line width - automatically scaled to image by default DESCRIPTION. The default is “auto”.
show_nodes (bool, optional) – show nodes of polyline. The default is False.
node_colour (str, optional) – colour of node points. The default is “default”.
node_size (int, optional) – size of node points. The default is “auto”.

Returns:

image – canvas with lines

Return type:

ndarray

phenopype.core.visualization.draw_QRcode(image, annotations, line_colour='default', line_width='auto', label=True, label_colour='default', label_size='auto', label_width='auto', **kwargs)¶

Parameters:

image (ndarray) – image used as canvas
annotation (dict) – phenopype annotation containing QR-code (comment)
line_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour line colour - default colour as specified in settings
line_width ({"auto", ... int > 0} int, optional) – contour line width - automatically scaled to image by default
label (bool, optional) – draw reference label
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour label colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – contour label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – contour label font thickness - automatically scaled to image by default
**kwargs (TYPE) – DESCRIPTION.

Returns:

canvas – DESCRIPTION.

Return type:

TYPE

phenopype.core.visualization.draw_reference(image, annotations, line_colour='default', line_width='auto', label=True, label_colour='default', label_size='auto', label_width='auto', **kwargs)¶

Parameters:

image (ndarray) – image used as canvas
annotation (dict) – phenopype annotation containing reference data
line_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour line colour - default colour as specified in settings
line_width ({"auto", ... int > 0} int, optional) – contour line width - automatically scaled to image by default
label (bool, optional) – draw reference label
label_colour ({"default", ... see phenopype.print_colours()} str, optional) – contour label colour - default colour as specified in settings
label_size ({"auto", ... int > 0} int, optional) – contour label font size - automatically scaled to image by default
label_width ({"auto", ... int > 0} int, optional) – contour label font thickness - automatically scaled to image by default

Returns:

canvas – DESCRIPTION.

Return type:

TYPE

phenopype.core.visualization.select_canvas(image, canvas='raw', multi_channel=True, invert=False, **kwargs)¶

Isolate a colour channel from an image or select canvas for the pype method.

Parameters:

image (ndarray) – image used as canvas
canvas ({"mod", "bin", "gray", "raw", "red", "green", "blue"} str, optional) – the type of canvas to be used for visual feedback. some types require a function to be run first, e.g. “bin” needs a segmentation algorithm to be run first. black/white images don’t have colour channels. coerced to 3D array by default
multi (bool, optional) – coerce returned array to multichannel (3-channel)

Returns:

canvas – canvas for drawing

Return type:

ndarray

Export¶

phenopype.core.export.convert_annotation(annotations, annotation_type, annotation_id, annotation_type_new, annotation_id_new, overwrite=False, **kwargs)¶

convert coordinates from one annotation type to another. currently, only converting from contour to mask format is possible

Parameters:

annotations (dict) – A phenopype annotation dictionary.
annotation_type (str | list of str) – If dict contains multiple annotation types, select one or more to load. None will load all types.
annotation_id (str | list of str) – If file contains multiple annotation IDs, select one or more to load. None will load all IDs within a type.
annotation_type_new (str) – target annotation type
annotation_id_new (str | list of str, optional) – target annotation id
overwrite (bool, optional) – if target exists, overwrite? The default is False.

Return type:

None.

phenopype.core.export.export_csv(annotations, dir_path, annotation_type=None, image_name=None, overwrite=False, **kwargs)¶

export annotations from json to csv format.

Parameters:

annotations (dict) – A phenopype annotation dictionary.
dir_path (str) – To which folder should the csv file be exported. PYPE: Automatically set to the current image directory
annotation_type (str / list, optional) – Which annotation types should be exported - can be string or list of strings.
image_name (str) – Image name to be added as a column PYPE: Automatically adds the image name.
overwrite (bool, optional) – Should an existing csv file be overwritten. The default is False.

Return type:

None.

phenopype.core.export.load_annotation(filepath, annotation_type=None, annotation_id=None, tag=None, **kwargs)¶

load phenopype annotations file

Parameters:

filepath (str) – Path to JSON file containing annotations
annotation_type (str | list of str, optional) – If file contains multiple annotation types, select one or more to load. None will load all types. The default is None.
annotation_id (str | list of str, optional) – If file contains multiple annotation IDs, select one or more to load. None will load all IDs within a type. The default is None.

Returns:

Loaded annotations.

Return type:

dict

phenopype.core.export.save_annotation(annotations, dir_path, annotation_type=None, annotation_id=None, overwrite=False, **kwargs)¶

save phenopype annotations file

Parameters:

annotation (dict) –

Annotation dictionary formatted by phenopype specifications:

{
    annotation_type = {
        annotation_id = annotation,
        annotation_id = annotation,
        ...
        },
    annotation_type = {
        annotation_id = annotation,
        annotation_id = annotation,
        ...
        },
    ...
}

annotation_id (str, optional) – String (“a”-“z”) specifying the annotation ID to be saved. None will save all IDs. The default is None.
dir_path (str, optional) – Path to folder where annotation should be saved. None will save the annotation in the current Python working directory. The default is None.
file_name (str, optional) – Filename for JSON file containing annotation. The default is “annotations.json”.
overwrite (bool, optional) –
Overwrite options should file or annotation entry in file exist:
- False = Neither file or entry will be overwritten
- True or “entry” = A single entry will be overwritten
- ”file” = The whole will be overwritten.
The default is False.

Return type:

None.

phenopype.core.export.save_ROI(image, annotations, dir_path, file_name, channel='raw', counter=True, which='all', suffix=None, rotate=False, rotate_padding=5, angle_apply=None, align='v', ext='jpg', background='original', canvas_dim=False, canvas_fit=False, min_dim=False, max_dim=False, padding=True, **kwargs)¶

Save a region of interest (ROI) indicated by contour or mask coordinates as a crop of the original image, optionally with white background

Parameters:

image (ndarray) – An image containing regions of interest (ROI).
annotations (dict) – A phenopype annotation dict containing one or more contour coordinate entries.
dir_path (str, optional) – Path to folder where annotation should be saved. None will save the annotation in the current Python working directory. The default is None.
file_name (str) – Name for ROI series (should reflect image content, not “ROI” or the like which is specified with prefix or suffix arguments). The contour index will be added as a numeric string at the end of the filename.
channel (str, optional) – Which channel to save. The default is “raw”.
counter (TYPE, optional) – Whether to add a contour to the filename. The default is True.
prefix (str, optional) – Prefix to prepend to individual ROI filenames. The default is None.
suffix (str, optional) – Suffix to append to individual ROI filenames. The default is “roi”.
extension (str, optional) – New e. The default is “png”.
background (str, optional) – Sets background. The default is “original”, providing the background contained within the bounding rectangle. “transparent” will produce a png file with tranparent background. “white”, “black” or any other color will produce a different background color.

Return type:

None.

phenopype.core.export.save_canvas(image, file_path, ext='jpg', resize=0.5, overwrite=True, **kwargs)¶

Parameters:

image (ndarray) – A canvas to be saved.
save_suffix (str) – A suffix to be appended to the filename.
dir_path (str) – Path to directory to save canvas.
resize (float, optional) – resize factor for the image (1 = 100%, 0.5 = 50%, 0.1 = 10% of

Return type:

None.