Command-line interface¶

Most configuration for camfi is done with a configuration file rather than with command-line arguments and options. Documentation for the configuration can be found here: Configuration.

Camfi makes a bunch of sub-commands available to the command line (listed below). If multiple commands are given to a single camfi command, they will be executed in sequence. For example, the command:

$ camfi \
      --input project.json --root datadir \
      --output project_with_wingbeats.json \
      load-exif extract-wingbeats write

will first load a VIA project from a file, then load EXIF metadata from the image files (in datadir) into the project (load-exif), then the camfi wingbeat extraction algoritm will be run to obtain wingbeat frequencies (extract-wingbeats), and finally the project will be written to project_with_wingbeats.json (write).

Another command:

$ camfi train annotate validate

would load a VIA project from a file, train an instance segmentation model using the images and (manually obtained) annotations in the project, and save the new model to disk (train). Then camfi would re-annotate (annotate) the images in the project using the newly trained model, saving the newly obtained annotations to a new file (assuming annotator is properly configured). Finally, camfi would validate the automatically-obtained annotations against the manually-obtained ones (validate). All this, while properly handling keeping training and test image sets separate where required (and as per the configuration).

usage: camfi [-h] [--version] [-c path] [-i path] [-o path] [-r dir] [-d] [-p]
             [-j path] [-y path] [-q] [-v]
             [command ...]

Positional Arguments¶

command

Possible choices: annotate, do-nothing, extract-wingbeats, filelist, filter-images, filter-regions, image-table, load-exif, region-table, table, train, validate, write, zip-images

One or more commands to be executed sequentially by camfi. Each command uses the same configuration, as specified by -c/--config.

Default: “do-nothing”

Named Arguments¶

--version

Show version and exit.

Default: False

-c, --config

Path to configuration file. Can be JSON (.json) or StrictYAML (.yaml|.yml). If no configuration file is supplied, a default (empty) configuration is used. Most commands require at least some configuration.

-i, --input

Path to input VIA project file. Replaces via_project_file in configuration file, providing an alternative to setting it in the configuration file.

-o, --output

Path to output file. Replaces default_output in configuration file, providing an alternative to setting specific outputs in the configuration file.

-r, --root

Directory containing all images for the project. Replaces root in configuration file.

-d, --disable-progress-bar

Disables progress bars. By default, disable on non-TTY.

-p, --progress-bar

Forces progress bars. By default, disable on non-TTY.

-j, --json-conf-out

If set, configuration will be written to file in JSON format after it is parsed. Set to - to have config written to stdout.

-y, --yaml-conf-out

If set, configuration will be written to file in StrictYAML format after it is parsed. Set to - to have config written to stdout.

-q, --quiet

Suppress cli info. You may also like to use -d.

Default: False

-v, --verbose

Extra verbose cli info.

Default: False

Below are the list of commands available to Camfi.

annotate: 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.
do-nothing: 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: 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: Lists the images in the VIA project to stdout or file (set using default_output configuration parameter or -o/--output).
filter-images: 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: 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: 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: 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: 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: 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: 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: 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: 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: Makes a zip archive of all the images in the VIA project file (default_output configuration parameter or -o/--output must be set).