camfi.cli module

Defines command-line interface to Camfi.

class camfi.cli.Commander(config_path: Optional[pathlib.Path], input_file: Optional[pathlib.Path] = None, root: Optional[pathlib.Path] = None, output: Optional[pathlib.Path] = None, disable_progress_bar: Optional[bool] = None, vprint: Callable = <function _vprint>, vvprint: Callable = <function _qprint>)

Bases: object

Defines commands for camfi cli. Any command defined on this class can be called by providing them as command-line arguments to camfi.

__call__(command: str) → None

Calls method of self corresponding to command.

Parameters

command (str) – Name of command to call. These are the same as the methods defined on this class. Any “-” characters are converted to “_” charaters.

__init__(config_path: Optional[pathlib.Path], input_file: Optional[pathlib.Path] = None, root: Optional[pathlib.Path] = None, output: Optional[pathlib.Path] = None, disable_progress_bar: Optional[bool] = None, vprint: Callable = <function _vprint>, vvprint: Callable = <function _qprint>)

Parses config_path file into self.config : camfi.projectconfig.CamfiConfig.

Parameters

  • config_path (Optional[Path]) – Path to configuration file. Can be JSON (.json) or StrictYAML (.yaml|.yml).

  • input_file (Optional[Path]) – Path to VIA project file. If set, self.config.via_project_file will be overwritten with this value.

  • root (Optional[Path]) – Path to root directory containing all images. If set, self.config.root will be overwritten with this value.

  • output (Optional[Path]) – If set, self.config.default_output will be overwritten with this value.

  • disable_progress_bar (Optional[bool]) – Option to force progress bars to be hidden or shown. If set, self.config.disable_project_bar will be overwritten with this value.

  • vprint (Callable) – Called for verbose printing.

  • vvprint (Callable) – Called for very verbose printing.

__weakref__

list of weak references to the object (if defined)

annotate() → None

Performs automatic annotation on all the images in via_project, outputting the resulting annotated VIA project file to the configured output_path specified under annotator.inference in the configuration file. Requires annotator.inference to be configured. While not strictly required, annotator.inference.output_path should be configured, otherwise the result of annotation will not be saved before the program terminates (and this is probably not what you want). Alternatively, you can configure default_output either in the configuration file or by using the -o/--output flag.

classmethod cmds() → dict

Returns the commands defined by this class.

Returns

commands – Dictionary with command names mapped to command docstrings.

Return type

dict[str, str]

do_nothing() → None

Does nothing, except parse options and configuration. This can be useful if all you want to do is validate and/or convert the configuration file. This is the default command which is run when camfi is called.

extract_wingbeats() → None

Runs the Camfi algorithm to extract wingbeat data from all images in the VIA project, inserting that data into the project in-place. Requires camera and wingbeat_extraction to be configured.

filelist() → None

Lists the images in the VIA project to stdout or file (set using default_output configuration parameter or -o/--output).

filter_images() → None

Applies filters to exclude images from VIA project. Operates in-place on the VIA project. Does nothing if filters.image_filters isn’t configured.

filter_regions() → None

Applies filters to exclude regions (annotations) from VIA project. Operates in-place on the VIA project. Does nothing if filters.region_filters isn’t configured.

image_table() → None

Produces a table with one row per image, with various image metadata columns, including n_annotations (the number of annotations in the image). Table is written to stout or file (set using default_output configuration parameter or -o/--output).

load_exif() → None

Loads EXIF metadata into VIA project in-place after reading it from file. If time (and optionally camera) are configured, then this will also insert location and corrected timestamp metadata.

region_table() → None

Produces a table with one row per region (annotation). Table is written to stout or file (set using default_output configuration parameter or -o/--output).

table() → None

Similar to image-table, but includes weather and sun time columns. Produces a table with one row per image, with various image metadata columns, including n_annotations (the number of annotations in the image). Table is written to stout or file (set using default_output configuration parameter or -o/--output).

train() → None

Trains a camfi instance segmentation annotation model on manually annotated dataset, saving to trained model to the outdir configured under annotator.training. Requires annotator.training to be configured. If annotator.inference is configured, but under it model has not been explicitely set, then after the model is trained model of annotator.inference will be set to the newly trained model. This means that with proper configuration, train and annotate can be strung together in one command (i.e. camfi train annotate).

validate() → None

Validates automatically aquired annotations against ground-truth annotations, saving the results to the output_dir configured under annotator.validation. Requires annotator.validation to be configured. While not strictly required, annotator.validation.output_dir should be configured, otherwise the result of validation will not be saved before the program terminates (and this is probably not what you want). If image_set under annotator.validation contains “train” or “test”, then test_set (or test_set_file) under annotator.training should also be configured. If annotator.training is not set, then the “train” image_set will be equivalent to “all”, and “test” will be an empty set of images. It is also possible to leave autoannotated_via_project_file under annotator.validation unconfigured. In this case, the output_path from annotation.inference will be validated (so at least one of these must be configured). Alternatively, you can configure default_output either in the configuration file or by using the -o/--output flag.

write() → None

Writes VIA project to stdout or file (set using default_output configuration parameter or -o/--output). Can be used after other commands which act in-place on the VIA project (e.g. load-exif, extract-wingbeats and apply-filters). Prints to stdout if no output is given.

zip_images() → None

Makes a zip archive of all the images in the VIA project file (default_output configuration parameter or -o/--output must be set).

exception camfi.cli.ConfigParseError

Bases: Exception

Raised if config parsing fails.

__weakref__

list of weak references to the object (if defined)

camfi.cli.get_argument_parser(show_rst: bool = True) → argparse.ArgumentParser

Defines arguments to the camfi command.

Parameters

show_rst (bool) – If False, reStructuredText will be ommitted from description and epilog.

Returns

parser – Command-line argument parser for camfi.

Return type

ArgumentParser