owl.stitch.hugin_stitching

owl.stitch.hugin_stitching(mcam_data_path, *, save_directory=None, stitch_filename=None, pto_filename=None, template_pto_filename=None, load_masks_filename=None, save_masks_filename=None, blender='enblend', estimated_overlap=(None, 0.35), selection_slice=None, cp_threshhold_dist=100, ignore_calibration=False, attempt_custom_alignment=False, use_gpu=False, output_shape=None, bbox_indices=None, primary_seam_generator='nft', text_output=None, **kwargs)[source]

Stitch mcam images using hugin.

stitches mcam images utilizing the hugin toolbox and exports the final stitched image as a tiff file.

Data can be stitched by giving only the mcam_data directory path as shown:

>>> from pathlib import Path
>>> from owl.stitch.hugin import hugin_stitching

>>> mcam_data_filename = Path('path_to_walkthrough_images')
>>> stitch_filename, pto_filename = hugin_stitching(mcam_data_filename)

Set pass a pto file path to template_pto_path to used premade template instead of creating a new one

>>> stitch_filename, pto_filename = hugin_stitching(mcam_data_path,
                                                    template_pto_filename=pto_filename)

Give a location to save the masks and the blending masks will be saved during blending

>>> save_masks_filename = mcam_data_filename / 'mask%n.tif'
>>> stitch_filename, pto_filename = hugin_stitching(mcam_data_path,
                                                    save_masks_filename=save_masks_filename)

Give a location to save the masks and the blending masks will be saved during blending

>>> load_masks_filename = save_masks_filename
>>> stitch_filename, pto_filename = hugin_stitching(mcam_data_path,
                                                    template_pto_filename=pto_filename,
                                                    load_masks_filename=load_masks_filename)

Designate the nona blender (default blender is enblend) - this is quicker, but seams are more obvious

>>> stitch_filename, pto_filename = hugin_stitching(mcam_data_path,
                                                    blender='nona')
Parameters:

  • mcam_data_path (PathLike) – The path to either the directory containing all of the exported images to stitch, or the single file path to the mcam_data.

  • save_directory (PathLike) – If provided, the stitched image and the pto file will be created in the provided path. By default, if an exported dataset is provided, the save_directory will be that of the dataset. If a single .nc file is provided, a new directory will be created with the same name as the stem of the .nc file.

  • stitch_filename (PathLike, optional) – Path to file that will contain the stitched tiff (extension will be appended). Default is stitched.tif in the save_directory.

  • pto_filename (PathLike, optional) – Path to the pto file containing all the stitching information (must include pto extension). Default is template.pto in the save_directory.

  • template_pto_filename (PathLike) – When paseed a pto path the given path will be used to find a prewriten pto file that will be used to align the images before blending. If it is not found or the file does not match the N_cameras the code will raise an error. If a template pto file is used, then a copy of the pto file modified to reflect the used blender is saved as template.pto in the same directory as the stitched image, or at the file path given to pto_path.

  • load_masks_filename (String or None) – If given a string the masks generated during the blending process are saved at the location given with the given file extension (tif is suggested). Include “%n” o add a counter to the name so that all masks have unique names. Only applies if blender=’enblend’. The default is None.

  • save_masks_filename (String or None) – If given a string the blender will attempt to load masks from the filename given. Use “%n” to reference indexed masks (similar to load_masks_path). Only applies if blender=’enblend’. Defaults to False.

  • blender ('enblend', 'nona', OR 'none') – This is the blending engine use for the stitched image. Enblend will use Dijkstra’s shortest path algorithm to minimize the difference between overlapping pixels along the seam, and nona will selects seams based on the watershed algorithm. Enblend provides less visible seams, but nona is much faster. If the blender is set to ‘none’ only the template will be generated, without creating a stitched image. The default is ‘enblend’.

  • estimated_overlap ((float, float), optional) – Percentage of image size is expected to overlap with neighboring images. (vertical, horizontal). The default is (0.13, 0.35).

  • selection_slice (slice) – Section of mcam_data array to stitch. If section is used with template the template must have been made using the same section. If section is None, full array will be used. When selecting a section of a saved dataset without camera index (0, 0), index as if the lowest indexed camera is (0, 0).

  • cp_threshhold_dist (Num) – The distance in pixels from the initial positioning that a control point pair can be. All points pairs a greater distance will be removed.

  • ignore_calibration (Boolean) – If True, ignores the calibrationg stitching transforms when generating initial alingments and instead using the given estimated overlap.

  • attempt_custom_alignment (Boolean) – If True will attempt to align images based on found control points. If False will stitch images based on initial position.

  • use_gpu (bool) – If True use the gpu to speed up the performance of nona. setting this to True with blender=’enblend’ decreases the time very slightly, but with blender=’nona’ the time to stitch decreases about 30%.

  • output_shape ((int, int)) – A tuple holding the desired dimensions of the composite image in (HEIGHT, WIDTH).

  • bbox_indices (((image_y0, image_x0, pix_y0, pix_x0), (image_y1, image_x1, pix_y1, pix_x1))) – Two diagnolly opposite points to define the bounding box. Points are in data array space meaning a point is defined by their camera index and pixel index.

  • primary_seam_generator (str) – The primary seam generator used by enblend. Set to either ‘graph-cut’ (‘gc’) or ‘nearest-feature-transform’ (‘nft’).

Returns:

  • stitch_filename (Path or None) – The path to the stitched image. If the blender is set to ‘none’ this value will be None.

  • pto_filename (Path) – The path to the template file containing the data necessary to create the global transforms.