Pype class¶
phenopype’s core method to process image datasets with high throughput and reproducibility. Should be used in conjunction with image organized in a Phenopype directory structure. The Pype
class has specific implicit behaviour that aims at supporting speed and robustness when working in “production” (i.e. when performing the actual analysis of large image datasets compared to prototyping and low throughput workflow). These are the most important things to keep in mind during a Pype
iteration
Important
Enhanced Window control
In addition to regular window control functions documented in Tutorial 2:
Editing and saving the opened configuration file in the text editor will trigger another iteration, i.e. close the image window and run the config file again.
Closing the image window manually (with the X button in the upper right), also runs triggers another run.
Esc
will close all windows and interrupt the pype routine (triggerssys.exit()
, which will also end a Python session if run from the command line), as well as any loops.Each step that requires user interaction (e.g.
create_mask
orlandmarks
) needs to be confirmed withEnter
until the next function in the sequence is executed.At the end of the analysis, when the final steps (visualization and export functions) have run, use
Ctrl+Enter
to finish and close the window.
Function execution
Pype
will automatically load the image and execute all functions in sequence, but it will not overwrite overwrite data from past iterations on disk unless specified.To overwrite interactive user input, set the argument
edit: true
oredit: overwrite
in the function’s annotation control arguments.If you forget to remove an overwrite argument and are prompted to overwrite previous input, immediately change to
edit: false
argument, and save the config file.If a
Pype
is initialized on a project directory it will attempt to load input data (e.g. masks) that contain the providedtag
argument. For example,pp.Pype(path, tag="v1"
will attempt to load any files in the directory that contain the suffix"v1"
(e.g."annoations_v1.json"
).
Visualizing the results
Aspects of visual feedback during a pype
run (can be completely
suppressed by setting visualize=False
:
Visual feedback (i.e. output from
landmarks
,detect_contours
orcreate_mask
) are drawn onto a “canvas” (a copy of the original image).Use
select_canvas
to draw the results either on the raw image, a binary image, or a single colour channel (gray, red, green or blue).If
select_canvas
is not explicitly specified, it is called automatically and defaults to the raw image as canvas.Output from all functions, needs to be specified manually. For example, after using
- landmarks
,- draw_landmarks
should be called in thevisualization
module.Visual parameters of interactive tools (e.g.
point_size
orline_thickness
) are specified separately in the respective function, and in thevisualization
module.
Exporting the results
Saving annotations, canvas and other results:
All results are saved automatically, even if the respective functions in
export
are not specified, with thetag
argument inPype
as suffix.If a file already exist in the directory, and the respective function is not listed under
export
, then it will not be overwritten.If an export function is specified under
export:
, it will also not overwrite any existing file, unless specified usingoverwrite: true
.The canvas is an exception: it will always be saved and always be overwritten (unless specified with
overwrite: False
to show the output from the last iteration. However, users can modify the canvas name withfile_name
in the arguments to save different output side by side. For example,file_name: binary
under- save_canvas:
save the canvas ascanvas_binary.jpg
- class phenopype.main.Pype(image_path, tag, config_path=None, skip=False, autoload=True, autosave=True, autoshow=True, fix_names=True, feedback=True, load_contours=False, zoom_memory=False, debug=False, **kwargs)¶
Bases:
object
The pype is phenopype’s core method that allows running all functions that are available in the program’s library in sequence. Users can execute the pype method on a file_path, an array, or a phenopype directory, which always will trigger three actions:
open the contained yaml configuration with the default OS text editor
parse the contained functions and execute them in the sequence (exceptions will be passed, but returned for diagnostics)
open a Python-window showing the processed image.
After one iteration of these steps, users can evaluate the results and decide to modify the opened configuration file (e.g. either change function parameters or add new functions), and run the pype again, or to terminate the pype and save all results. The processed image, any extracted phenotypic information, as well as the modified config-file is stored inside the image directory, or a user-specified directory. By providing unique names, users can store different pype configurations and the associated results side by side.
- Parameters
image (array or str) – can be either a numpy array or a string that provides the path to source image file or path to a valid phenopype directory
name (str) – name of pype-config - will be appended to all results files
config_template (str, optional) – chose from list of provided templates (e.g. ex1, ex2, …)
config_path (str, optional) – custom path to a pype template (needs to adhere yaml syntax and phenopype structure)
delay (int, optional) – time in ms to add between reload attemps of yaml monitor. increase this value if saved changes in config file are not parsed in the first attempt.
dir_path (str, optional) – path to an existing directory where all output should be stored
skip (bool, optional) – skip directories that already have “name” as a suffix in the filename
feedback (bool, optional) – don’t open text editor or window, just apply functions and terminate
max_dim (int, optional) – maximum dimension that window can have
kwargs – developer options