Utility functions

Utility functions, e.g. to load and display images ,e.g. pp.utils.load_image() and pp.utils.show_image(). Any of these functions can be called directly after loading phenopype without the need to add the utils submodule:

import phenopype as pp

image_path = "image_dir/my_image.jpg"

image = pp.load_image(image_path)       # instead of pp.utils.load_image
pp.show_image(image)                    # instead of pp.utils.show_image
dir(pp)                                 # shows available classes and functions
phenopype.utils.load_image(path, mode='unchanged', **kwargs)

Create ndarray from image path or return or resize exising array.

  • path (str) – path to an image stored on the harddrive

  • mode ({"default", "colour","gray"} str, optional) –

    image conversion on loading:
    • default: load image as is

    • colour: convert image to 3-channel (BGR)

    • gray: convert image to single channel (grayscale)

  • kwargs – developer options


  • container (container) – A phenopype container is a Python class where loaded images, dataframes, detected contours, intermediate output, etc. are stored so that they are available for inspection or storage at the end of the analysis.

  • image (ndarray) – original image (resized, if selected)

phenopype.utils.resize_image(image, factor=1, factor_ret=False, width=None, height=None, max_dim=None, interpolation='cubic')

Resize image by resize factor

  • image (array) – image to be resized

  • max_dim (int, optional) – maximum size of any dimension that the image will be resized to. if image is smaller, no resizing will be performed. maintains aspect ratio

  • factor (float, optional) – resize factor for the image (1 = 100%, 0.5 = 50%, 0.1 = 10% of original size). at 1, no resizing will be performed

  • interpolation ({'nearest', 'linear', 'cubic', 'area', 'lanczos', 'lin_exact', 'inter', 'warp_fill', 'warp_inverse'} str, optional) – interpolation algorithm to use - refer to https://docs.opencv.org/3.4.9/da/d54/group__imgproc__transform.html#ga5bb5a1fea74ea38e1a5445ca803ff121


image – resized image

Return type:


phenopype.utils.save_image(image, file_name, dir_path, suffix=None, ext='jpg', overwrite=False)

Save an image (array) to a specified format.

  • image (array) – Image to save.

  • file_name (str) – Base name for the saved image.

  • dir_path (str) – Directory to save the image.

  • suffix (str, optional) – Suffix to append to the image name to prevent overwriting.

  • ext (str, optional) – File extension to save image as.

  • overwrite (bool, optional) – If True, overwrite existing files with the same name.


True if the image was saved successfully, False otherwise.

Return type:


phenopype.utils.show_image(image, return_input=False, position_reset=True, position_offset=25, window_aspect='normal', check=True, **kwargs)

Show one or multiple images by providing path string or array or list of either.

  • image (array, list of arrays) – the image or list of images to be displayed. can be array-type, or list or arrays

  • window_max_dim (int, optional) – maximum dimension on either acis

  • window_aspect ({"fixed", "free"} str, optional) – type of opencv window (“free” is resizeable)

  • position_reset (bool, optional) – flag whether image positions should be reset when reopening list of images

  • position_offset (int, optional) – if image is list, the distance in pixels betweeen the positions of each newly opened window (only works in conjunction with “position_reset”)

  • check (bool, optional) – user input required when more than 10 images are opened at the same time