Configuration

Rather than relying on command-line options or environment variables, Camfi is configured using a configuration file which can be either JSON or YAML (actually, a subset of YAML called StrictYAML). This makes camfi experiments much more reproducible.

It is suggested to create a camfi configuration file before heading out into the field to set up your cameras. Then you can start putting in some of the metadata (e.g. camera placement info) as you go. This will make your life a lot easier when it comes time to analyse your data.

The JSON-Schema for camfi configuration files is available here. It should be possible to use the schema to generate a web IU form for easily producing json configuration files for Camfi, however this has not been implemented. raise an issue on GitHub if you plan on using Camfi and would like to use something like that rather than a text editor.

Example configuration file

Below is an example configuration file in yaml format. The same configuration is also available in json format.

root: data
via_project_file: data/cabramurra_all_annotations.json
day_zero: 2019-01-01
output_tz: +10:00
filters:
  image_filters:
    min_annotations: 1
camera:
  camera_time_to_actual_time_ratio: 1.0
  line_rate: 9.05e+04
time:
  camera_placements:
    2019-11_cabramurra/0004:
      camera_start_time: 2019-10-14T13:00:00+11:00
      actual_start_time: 2019-11-14T13:00:00+11:00
      location: cabramurra
    2019-11_cabramurra:
      camera_start_time: 2019-11-14T13:00:00+11:00
      location: cabramurra
place:
  locations:
  - name: cabramurra
    lat: -35.9507
    lon: 148.3972
    elevation_m: 1513.9
    tz: +10:00
  weather_stations:
  - location:
      name: cabramurra_smhea_aws_072161
      lat: -35.94
      lon: 148.38
      elevation_m: 1482.4
      tz: +10:00
    data_file: data/cabramurra_bom_weather_201911.csv
  location_weather_station_mapping:
    cabramurra: cabramurra_smhea_aws_072161
wingbeat_extraction:
  device: cpu
  scan_distance: 50
annotator:
  crop:
    x0: 0
    y0: 0
    x1: 4608
    y1: 3312
  training:
    mask_maker:
      shape:
      - 3312
      - 4608
      mask_dilate: 5
    min_annotations: 1
    max_annotations: 50
    test_set_file: data/cabramurra_test_set.txt
    device: cuda
    batch_size: 5
    num_workers: 2
    num_epochs: 15
    outdir: data
    save_intermediate: true
  inference:
    output_path: data/cabramurra_autoannotated.json
    device: cuda
    backup_device: cpu
    score_thresh: 0.0
  validation:
    autoannotated_via_project_file: data/cabramurra_autoannotated.json
    image_sets:
    - all
    - test
    - train
    output_dir: data

Configuration specification

What follows is the specification for Camfi configuration files rendered into a tabulated format.

CamfiConfig

Camfi configuration.

type	object
properties
root	Root
	Directory containing all images for the project.
	type	string
	default	.
	format	directory-path
disable_progress_bar	Disable Progress Bar
	Disables progress bars. By default, disable on non-TTY. To force the progress bar to appear, set this to false.
	type	boolean
via_project_file	Via Project File
	Path to file containing VIA project. Can either be given as a single path or a list of paths. If a list is given, then the VIA projects will be merged.
	anyOf	type	array
		items	type	string
			format	file-path
		type	string
		format	file-path
day_zero	Day Zero
	Used as reference date for plotting etc. Currently the Camfi CLI does not access this value, However it is used in some of the example notebooks.
	type	string
	format	date
output_tz	Timezone
	Sets a global timezone to convert all timezones to, for simpler comparison between locations in different timezones.
	type	string
	examples	Z
		+10:00
		-05
	pattern	^Z|[+-]\d{2}(?::?\d{2})?$
default_output	Default Output
	Path to write output. Outputs defined in wingbeat_extractor and annotator take precedence over this.
	type	string
	format	path
filters	FilterConfig
camera	CameraConfig
time	LocationTimeCollector
place	LocationWeatherStationCollector
wingbeat_extraction	WingbeatExtractorConfig
annotator	AnnotatorConfig

ImageFilterConfig

Contains options for filtering images from a VIA project.

type	object
properties
min_annotations	Min Annotations
	Exclude images if they have fewer annotations than this.
	type	integer
exclude_images	Exclude Images
	Images to exclude from VIA project. Can either be a list of paths to image files, or a single path to a text file (i.e. not a list). If the latter, image file paths will be read from text file, one per line.
	type	array
	items	type	string
		format	path
include_images	Include Images
	Images to include from VIA project. Images not in this list will be excluded. Can either be a list of paths to image files, or a single path to a text file (i.e. not a list). If the latter, image file paths will be read from text file, one per line.
	type	array
	items	type	string
		format	path

FloatFilter

type	object
properties
ge	Greater-than or Equal-to
	Only include region if attribute >= this value.
	type	number
le	Less-than or Equal-to
	Only include region if attribute <= this value.
	type	number
exclude_none	Exclude None
	Whether to exclude region if attribute is not set.
	type	boolean
	default	False

RegionFilterConfig

Contains options for filtering regions (annotations) from images, based on the values of region attributes.

type	object
properties
score	Score
	Sets filters for the score region attribute.
	allOf	FloatFilter
best_peak	Best Peak
	Sets filters for the best_peak region attribute.
	allOf	FloatFilter
blur_length	Blur Length
	Sets filters for the blur_length region attribute.
	allOf	FloatFilter
snr	Snr
	Sets filters for the snr region attribute.
	allOf	FloatFilter
wb_freq_up	Wb Freq Up
	Sets filters for the wb_freq_up region attribute.
	allOf	FloatFilter
wb_freq_down	Wb Freq Down
	Sets filters for the wb_freq_down region attribute.
	allOf	FloatFilter
et_up	Et Up
	Sets filters for the et_up region attribute.
	allOf	FloatFilter
et_dn	Et Dn
	Sets filters for the et_dn region attribute.
	allOf	FloatFilter

FilterConfig

Contains settings for filtering images and/or regions (annotations) from a VIA project.

type	object
properties
image_filters	ImageFilterConfig
region_filters	RegionFilterConfig

CameraConfig

Camera hardware-related configuration.

type	object
properties
camera_time_to_actual_time_ratio	Camera Time To Actual Time Ratio
	Used for correcting timestamps from an inaccurate clock. A value of 1.0 means the camera’s clock runs at the correct speed. A value less than 1.0 means that the camera’s clock is slow, and a value greater than 1.0 means the camera’s clock is fast.
	type	number
line_rate	Line Rate
	Rolling-shutter line rate of camera (lines per second). Used during wingbeat extraction to determine the effective exposure time for moving objects (flying insects) in images. This is required in order to calculate wingbeat frequency accurately.
	type	number
	exclusiveMinimum	0

LocationTime

Camera placement data

type	object
properties
camera_start_time	Camera Start Time
	Camera placement datetime (according to camera’s clock).
	type	string
	format	date-time
actual_start_time	Actual Start Time
	Actual camera placement datetime (defaults to camera_start_time).
	type	string
	format	date-time
camera_end_time	Camera End Time
	Camera retrieval time (according to camera’s clock).
	type	string
	format	date-time
actual_end_time	Actual End Time
	Actual camera retrieval time.
	type	string
	format	date-time
location	Location
	Name of location the camera was placed in.
	type	string

LocationTimeCollector

Contains data for multiple camera placements.

type	object
properties
camera_placements	Camera Placements
	Mapping from sub-directories containing images to LocationTime instances.
	type	object
	additionalProperties	LocationTime

Location

Contains spatial data on locations, including timezone.

type	object
properties
name	Name
	Name of location. Used to link to camera placements.
	type	string
lat	Lat
	Decimal latitude.
	type	number
lon	Lon
	Decimal longitude.
	type	number
elevation_m	Elevation M
	Elevation in metres.
	type	number
	minimum	0
tz	Timezone
	ISO8601 timezone offset.
	type	string
	examples	Z
		+10:00
		-05
	pattern	^Z|[+-]\d{2}(?::?\d{2})?$

WeatherStation

Contains information on a weather station.

type	object
properties
location	Location
	Location of weather station.
	allOf	Location
data_file	Data File
	Path to csv file containing weather data from weather station. The firt 6 lines of the file are skipped, and the 7th should contain column headers. Should have one line per date. Minimally, the first column should be date, in YYYY-mm-dd format.
	type	string
	format	file-path

LocationWeatherStationCollector

Defines Locations and Weather stations.

type	object
properties
locations	Locations
	list of locations where cameras have been placed.
	type	array
	items	Location
weather_stations	Weather Stations
	list of weather stations.
	type	array
	items	WeatherStation
location_weather_station_mapping	Location Weather Station Mapping
	A mapping between location names and weather_station names.
	type	object
	additionalProperties	type	string

WingbeatExtractorConfig

Contains configurable parameters for WingbeatExtractor.

type	object
properties
device	Device
	Using GPU (‘cuda’) can give 4x speedups for certain operations.
	type	string
	default	cpu
backup_device	Backup Device
	Used when computation fails on main device due to memory limit.
	type	string
scan_distance	Scan Distance
	Max. distance from polyline used for wingbeat extraction.
	type	integer
	exclusiveMinimum	0
	default	50
max_pixel_period	Max Pixel Period
	Max. pixel period to check during wingbeat extraction.
	type	integer
	exclusiveMinimum	0
force_load_exif_metadata	Force Load Exif Metadata
	Forces EXIF metadata to be read from image instead of ViaProject.
	type	boolean
	default	False

BoundingBox

Defines a bounding box with integer (pixel) coordinates.

type	object
properties
x0	X0
	Minimum inclusive (horizontal) x-coordinate of box.
	type	integer
	minimum	0
y0	Y0
	Minimum inclusive (vertical) y-coordinate of box.
	type	integer
	minimum	0
x1	X1
	Maximum exclusive (horizontal) x-coordinate of box.
	type	integer
	minimum	0
y1	Y1
	Maximum exclusive (vertical) y-coordinate of box.
	type	integer
	minimum	0

MaskMaker

Contains settings for segmentation mask generation.

type	object
properties
shape	Shape
	Shape of images (height, width) in pixels.
	type	array
	items
		type	integer
		exclusiveMinimum	0
		type	integer
		exclusiveMinimum	0
mask_dilate	Mask Dilate
	Morphological dilation to apply to segmentation skeletons.
	type	integer
	exclusiveMinimum	0

TrainingConfig

Contains settings for camfi annotator model training.

type	object
properties
mask_maker	MaskMaker
min_annotations	Min Annotations
	Only train on images which have at least this many annotations. It often makes sense to set this to a low number (e.g. 1). This will mean that any image with no annotations in it will be skipped.
	type	integer
max_annotations	Max Annotations
	Only train on images which have at most this many annotations. This option exists because GPU memory consumption during each step of training depends on the number of annotations in the loaded images, so images with a lot of annotations can cause training to crash. It probably makes sense to leave this unset, and only set it if you are runnning into GPU memory errors.
	type	integer
box_margin	Box Margin
	Margin (in pixels) to add to bounding boxes of object annotations. This may affect endpoint estimation of polyline annotataions during inference.
	type	integer
	exclusiveMinimum	0
	default	10
test_set_file	Test Set File
	Path to file containing filepaths (one per line). Do not set if test_set is set.
	type	string
	format	file-path
test_set	Test Set
	list of images to exclude from training. Also used by validator to determine which subsets of images to validate against.
	type	array
	default
	items	type	string
		format	path
load_pretrained_model	Load Pretrained Model
	Path or url to model .pth file or one of camfi.models.model_urls to initialise training. By default, Resnet50 FPN backbone trained on the COCO dataset is used.
	examples	v1
		v2
		v2.1.4
		release
	anyOf	type	string
		format	path
		type	string
device	Device
	Device to run training on. Use cuda for a Nvidia GPU.
	type	string
	examples	cuda
		cpu
	default	cpu
batch_size	Batch Size
	Number of images to load at once. This has memory consumption implications, So if you’re running in to problems with memory availability on the GPU, consider lowering this.
	type	integer
	default	5
num_workers	Num Workers
	Number of worker processes for data loader to spawn. Depending on your machine, setting this really high can have diminishing returns as system IO will become the rate-limiting step.
	type	integer
	default	2
num_epochs	Num Epochs
	Number of epochs (traversals of the entire training set) to train. Note that data augmentation (e.g. random horizontal flipping) is applied only once to each image during each epoch.
	type	integer
	default	10
outdir	Outdir
	Path to directory where to save model (or models if save_intermediate is set).
	type	string
	default	.
	format	directory-path
model_name	Model Name
	Identifier to include in the file name of the trained model(s). By default, this will be inferred from the date the configuration is parsed, in the format YYYYmmdd.
	type	string
save_intermediate	Save Intermediate
	If True, model is saved after each epoch. By default, the model is only saved at the very end.
	type	boolean
	default	False

InferenceConfig

Contains settings for camfi annotator inference.

type	object
properties
output_path	Output Path
	If set, automatically generated annotations will be written to the file at the specified path. If unset, then the annotations will be written to the file at the path specified by CamfiConfig.default_output. If neither is set, the annotations will not be written to file, which is probably only useful if you are using camfi as a python module, rather than from the command line.
	type	string
	format	path
model	Model
	Pre-trained instance segmentation model to use during automated annotaton. Can be a path or url to a model .pth file or one of camfi.models.model_urls.
	examples	v1
		v2
		v2.1.4
		release
	default	release
	anyOf	type	string
		format	path
		type	string
device	Device
	Specifies device to run inference on.
	type	string
	examples	cpu
		cuda
	default	cpu
backup_device	Backup Device
	Used for images which fail on device due to memory constraints. It is recommended to set this to ‘cpu’ if device is set to ‘cuda’.
	type	string
split_angle	Split Angle
	Approximate maximum angle between polyline segments in degrees.
	type	number
	exclusiveMinimum	0
	default	15.0
poly_order	Poly Order
	Order of polynomial used for fitting motion blur paths.
	type	integer
	exclusiveMinimum	0
	default	2
endpoint_method	Endpoint Method
	Method to find endpoints of motion blurs.
	type	string
	examples	truncate
	default	truncate
endpoint_extra_args	Endpoint Extra Args
	Extra arguments to pass to endpoint method function.
	type	array
	default	10
	items
score_thresh	Score Thresh
	Score threshold between 0.0 and 1.0 for automatic annotations to be kept.Setting this to higher values will result fewer annotations being made.
	type	number
	default	0.0
overlap_thresh	Overlap Thresh
	Minimum weighted IoM between 0.0 and 1.0 for non- maximum suppression of detections. Setting this to higher values will result in a higher number of annotations being made, since fewer pairs of annotations will be assumed to relate to the same object as eachother.
	type	number
	default	0.4
edge_thresh	Edge Thresh
	Polyline annotations which go this close (measured in pixels) to edge of the image will be converted to circle annotations. This is because wingbeat measurements cannot be made unless the entire motion blur is contained within the image.
	type	integer
	minimum	0
	default	20

ValidationConfig

Contains settings for camfi annotator validation.

type	object
properties
autoannotated_via_project_file	Autoannotated Via Project File
	Path to file containing VIA Project with automatically obtained annotations to validate.
	type	string
	format	path
iou_thresh	Iou Thresh
	Threshold of bounding-box intersection-over-union to match automatically obtained annotations to ground truth annotations.
	type	number
	default	0.5
image_sets	Image Sets
	Image sets to perform validation on. Possible sets are ‘all’, ‘test’, and ‘train’. Multiple sets can be specified. If including ‘test’ or ‘train’, annotator.training must also be configured.
	type	array
	pattern	^(all|test|train)$
	default	all
	items	type	string
		pattern	^(all|test|train)$
output_dir	Output Dir
	If set, results of validation will be saved to this directory (one file per image set).
	type	string
	format	directory-path
output_stem	Output Stem
	Stem of output files. Output files will be saved as output_dir/output_stem.image_set.json.
	type	string
	default	validation

AnnotatorConfig

Settings for automatic annotation training and inference.

type	object
properties
crop	BoundingBox
training	TrainingConfig
inference	InferenceConfig
validation	ValidationConfig