TGrabs parameters

Note

TGrabs has a live-tracking feature, allowing users to extract positions and postures of individuals while recording/converting. For this process, all parameters relevant for tracking are available in TGrabs as well – for a reference of those, please refer to TRex parameters.

adaptive_threshold_scale(float)

default value: 2

Threshold value to be used for adaptive thresholding, if enabled.

approximate_length_minutes(uint)

default value: 0

If available, please provide the approximate length of the video in minutes here, so that the encoding strategy can be chosen intelligently. If set to 0, infinity is assumed. This setting is overwritten by stop_after_minutes.

See also

stop_after_minutes(),

average_samples(uint)

default value: 100

Number of samples taken to generate an average image. Usually fewer are necessary for `average_method`s max, and min.

See also

average_method(),

averaging_method(averaging_method_t)

default value: mean

possible values:
  • mean: Sum all samples and divide by N.

  • mode: Calculate a per-pixel median of the samples to avoid noise. More computationally involved than mean, but often better results.

  • max: Use a per-pixel minimum across samples. Usually a good choice for short videos with black backgrounds and individuals that do not move much.

  • min: Use a per-pixel maximum across samples. Usually a good choice for short videos with white backgrounds and individuals that do not move much.

Determines the way in which the background samples are combined. The background generated in the process will be used to subtract background from foreground objects during conversion.

blob_size_range(rangef)

default value: [0.01,500000]

Minimum or maximum size of the individuals on screen after thresholding. Anything smaller or bigger than these values will be disregarded as noise.

cam_framerate(int)

default value: 30

[BASLER] If set to anything else than 0, this will limit the basler camera framerate to the given fps value.

cam_limit_exposure(int)

default value: 5500

[BASLER] Sets the cameras exposure time in micro seconds.

cam_resolution(size<int>)

default value: [2048,2048]

[BASLER] Defines the dimensions of the camera image.

closing_size(int)

default value: 3

Size of the dilation/erosion filters for if use_closing is enabled.

See also

use_closing(),

color_channel(ulong)

default value: 1

Index (0-2) of the color channel to be used during video conversion, if more than one channel is present in the video file.

correct_luminance(bool)

default value: false

Attempts to correct for badly lit backgrounds by evening out luminance across the background.

crop_offsets(offsets)

default value: [0,0,0,0]

Percentage offsets [left, top, right, bottom] that will be cut off the input images (e.g. [0.1,0.1,0.5,0.5] will remove 10%% from the left and top and 50%% from the right and bottom and the video will be 60%% smaller in X and Y).

crop_window(bool)

default value: false

If set to true, the grabber will open a window before the analysis starts where the user can drag+drop points defining the crop_offsets.

dilation_size(int)

default value: 0

If set to a value greater than zero, detected shapes will be inflated (and potentially merged). When set to a value smaller than zero, detected shapes will be shrunk (and potentially split).

enable_closed_loop(bool)

default value: false

When enabled, live tracking will be executed for every frame received. Frames will be sent to the ‘closed_loop.py’ script - see this script for more information. Sets enable_live_tracking to true. Allows the tracker to skip frames by default, in order to catch up to the video.

See also

enable_live_tracking(),

enable_difference(bool)

default value: true

Enables background subtraction. If disabled, threshold will be applied to the raw greyscale values instead of difference values.

See also

threshold(),

enable_live_tracking(bool)

default value: false

When enabled, the program will save a .results file for the recorded video plus export the data (see output_graphs in the tracker documentation).

See also

output_graphs(),

equalize_histogram(bool)

default value: false

Equalizes the histogram of the image before thresholding and background subtraction.

ffmpeg_crf(uint)

default value: 20

Quality for crf (see ffmpeg documentation) used when encoding as libx264.

grabber_force_settings(bool)

default value: false

If set to true, live tracking will always overwrite a settings file with filename.settings in the output folder.

See also

filename(),

grabber_use_threads(bool)

default value: true

Use threads to process images (specifically the blob detection).

image_adjust(bool)

default value: false

Converts the image to floating-point (temporarily) and performs f(x,y) * image_contrast_increase + image_brightness_increase plus, if enabled, squares the image (image_square_brightness).

See also

image_contrast_increase(), image_brightness_increase(), image_square_brightness(),

image_brightness_increase(float)

default value: 0

Value that is added to the preprocessed image before applying the threshold (see image_adjust). The neutral value is 0 here.

See also

image_adjust(),

image_contrast_increase(float)

default value: 3

Value that is multiplied to the preprocessed image before applying the threshold (see image_adjust). The neutral value is 1 here.

See also

image_adjust(),

image_square_brightness(bool)

default value: false

Squares the floating point input image after background subtraction. This brightens brighter parts of the image, and darkens darker regions.

mask_path(path)

default value: “”

Path to a video file containing a mask to be applied to the video while recording. Only works for conversions.

meta_age_days(int)

default value: -1

Age of the individuals used in days.

meta_build(string)

default value: “”

The current commit hash. The video is branded with this information for later inspection of errors that might have occured.

meta_cmd(string)

default value: “”

Command-line of the framegrabber when conversion was started.

meta_conditions(string)

default value: “”

Treatment name.

meta_conversion_time(string)

default value: “”

This contains the time of when this video was converted / recorded as a string.

meta_misc(string)

default value: “”

Other information.

meta_species(string)

default value: “”

Name of the species used.

meta_write_these(array<string>)

default value: [“meta_species”,”meta_age_days”,”meta_conditions”,”meta_misc”,”cam_limit_exposure”,”meta_real_width”,”meta_source_path”,”meta_cmd”,”meta_build”,”meta_conversion_time”,”frame_rate”,”cam_undistort_vector”,”cam_matrix”]

The given settings values will be written to the video file.

quit_after_average(bool)

default value: false

If set to true, this will terminate the program directly after generating (or loading) a background average image.

recording(bool)

default value: true

If set to true, the program will record frames whenever individuals are found.

reset_average(bool)

default value: false

If set to true, the average will be regenerated using the live stream of images (video or camera).

save_raw_movie(bool)

default value: false

Saves a RAW movie (.mov) with a similar name in the same folder, while also recording to a PV file. This might reduce the maximum framerate slightly, but it gives you the best of both worlds.

stop_after_minutes(uint)

default value: 0

If set to a value above 0, the video will stop recording after X minutes of recording time.

system_memory_limit(uint64)

default value: 0

Custom override of how many bytes of system RAM the program is allowed to fill. If approximate_length_minutes or stop_after_minutes are set, this might help to increase the resulting RAW video footage frame_rate.

See also

approximate_length_minutes(), stop_after_minutes(),

terminate_error(bool)

default value: false

Internal variable.

test_image(string)

default value: “checkerboard”

Defines, which test image will be used if video_source is set to ‘test_image’.

See also

video_source(),

threshold(int)

default value: 9

Threshold to be applied to the input image to find blobs.

threshold_maximum(int)

default value: 255

use_adaptive_threshold(bool)

default value: false

Enables or disables adaptive thresholding (slower than normal threshold). Deals better with weird backgrounds.

use_closing(bool)

default value: false

Toggles the attempt to close weird blobs using dilation/erosion with closing_size sized filters.

See also

closing_size(),

video_conversion_range(pair<int, int>)

default value: [-1,-1]

If set to a valid value (!= -1), start and end values determine the range converted.

video_source(string)

default value: “basler”

Where the video is recorded from. Can be the name of a file, or one of the keywords [‘basler’, ‘webcam’, ‘test_image’].