diff --git a/docs/parameters_tgrabs.rst b/docs/parameters_tgrabs.rst index eaae708786373644179fdc3faa6f99a0934664f1..533620e905e90e7f2dd3f8b92c01b3389d6c7a88 100644 --- a/docs/parameters_tgrabs.rst +++ b/docs/parameters_tgrabs.rst @@ -182,16 +182,6 @@ TGrabs parameters -.. function:: video_source(string) - :noindex: - - **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']. - - - .. function:: video_conversion_range(pair<int,int>) :noindex: @@ -274,6 +264,16 @@ TGrabs parameters +.. function:: video_source(string) + :noindex: + + **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']. + + + .. function:: image_contrast_increase(float) :noindex: diff --git a/docs/parameters_trex.rst b/docs/parameters_trex.rst index c49ed5ea7a677e673ff3026f893bddba953644cc..fad836a43279a9fcf0429bd6992abfe7e1ba822b 100644 --- a/docs/parameters_trex.rst +++ b/docs/parameters_trex.rst @@ -57,6 +57,15 @@ TRex parameters +.. function:: huge_timestamp_seconds(double) + + **default value:** 0.2 + + + Defaults to 0.5s (500ms), can be set to any value that should be recognized as being huge. + + + .. function:: huge_timestamp_ends_segment(bool) **default value:** true @@ -66,7 +75,7 @@ TRex parameters -.. function:: track_blacklist(array<array<vec>>) +.. function:: track_ignore(array<array<vec>>) **default value:** [] @@ -311,6 +320,16 @@ TRex parameters .. seealso:: :func:`output_image_per_tracklet`, +.. function:: track_include(array<array<vec>>) + + **default value:** [] + + + If this is not empty, objects within the given rectangles or polygons (>= 3 points) [[x0,y0],[x1,y1](, ...)], ...] will be the only objects being tracked. (overwrites `track_ignore`) + + .. seealso:: :func:`track_ignore`, + + .. function:: cm_per_pixel(float) **default value:** 0 @@ -759,7 +778,7 @@ TRex parameters .. function:: version(string) - **default value:** "RC6" + **default value:** "1.0" Current application version. @@ -821,43 +840,6 @@ TRex parameters -.. function:: output_image_per_tracklet(bool) - - **default value:** false - - - If set to true, the program will output one median image per tracklet (time-series segment) and save it alongside the npz/csv files. - - - -.. function:: gui_show_texts(bool) - - **default value:** true - - - Showing or hiding individual identity (and related) texts in tracking view. - - - -.. function:: postures_per_thread(float) - - **default value:** 1 - - - Number of individuals for which postures will be estimated per thread. - - - -.. function:: outline_curvature_range_ratio(float) - - **default value:** 0.03 - - - Determines the ratio between number of outline points and distance used to calculate its curvature. Program will look at index +- `ratio * size()` and calculate the distance between these points (see posture window red/green color). - - .. seealso:: :func:`ratio * size()`, - - .. function:: event_min_peak_offset(float) **default value:** 0.15 @@ -940,6 +922,33 @@ TRex parameters +.. function:: postures_per_thread(float) + + **default value:** 1 + + + Number of individuals for which postures will be estimated per thread. + + + +.. function:: build_type(string) + + **default value:** "$<$<CONFIG:Debug>:Release>$<$<CONFIG:Release>:Debug>" + + + The mode the application was built in. + + + +.. function:: gui_show_texts(bool) + + **default value:** true + + + Showing or hiding individual identity (and related) texts in tracking view. + + + .. function:: gui_zoom_limit(size) **default value:** [300,300] @@ -1040,6 +1049,15 @@ TRex parameters +.. function:: build_cxx_options(string) + + **default value:** " -Wno-c++98-compat-pedantic -fvisibility=hidden -O3 -DNDEBUG -O3 -Wno-nullability-extension" + + + The mode the application was built in. + + + .. function:: midline_invert(bool) **default value:** false @@ -1175,33 +1193,6 @@ TRex parameters -.. function:: web_time_threshold(float) - - **default value:** 0.05 - - - Maximum refresh rate in seconds for the web interface. - - - -.. function:: midline_walk_offset(float) - - **default value:** 0.025 - - - This percentage of the number of outline points is the amount of points that the midline-algorithm is allowed to move left and right upon each step. Higher numbers will make midlines more straight, especially when extremities are present (that need to be skipped over), but higher numbers will also potentially decrease accuracy for less detailed objects. - - - -.. function:: gui_show_histograms(bool) - - **default value:** false - - - Equivalent to the checkbox visible in GUI on the bottom-left. - - - .. function:: outline_use_dft(bool) **default value:** true @@ -1348,24 +1339,6 @@ TRex parameters -.. function:: error_terminate(bool) - - **default value:** false - - - - - - -.. function:: exec(path) - - **default value:** "" - - - This can be set to the path of an additional settings file that is executed after the normal settings file. - - - .. function:: gui_heatmap_frames(uint) **default value:** 0 @@ -1393,6 +1366,7 @@ TRex parameters - `none`: No normalization at all. Values will only be averaged per cell. - `value`: Normalization based in value-space. The average of each cell will be divided by the maximum value encountered. - `cell`: The cell sum will be divided by the maximum cell value encountered. + - `variance`: Displays the variation within each cell. Normalization used for the heatmaps. If `value` is selected, then the maximum of all values encountered will be used to normalize the average of each cell. If `cell` is selected, the sum of each cell will be divided by the maximum cell value encountered. @@ -1400,6 +1374,52 @@ TRex parameters .. seealso:: :func:`value`, :func:`cell`, +.. function:: blob_split_global_shrink_limit(float) + + **default value:** 0.2 + + + The minimum percentage of the minimum in `blob_size_ranges`, that a blob is allowed to be reduced to during splitting. If this value is set too low, the program might start recognizing parts of individual as other individual too quickly. + + .. seealso:: :func:`blob_size_ranges`, + + +.. function:: blobs_per_thread(float) + + **default value:** 150 + + + Number of blobs for which properties will be calculated per thread. + + + +.. function:: gui_heatmap_smooth(double) + + **default value:** 0 + + + Value between 0 and 1, think of as `gui_heatmap_smooth` times video width, indicating the maximum upscaled size of the heatmaps shown in the tracker. Makes them prettier. + + + +.. function:: error_terminate(bool) + + **default value:** false + + + + + + +.. function:: exec(path) + + **default value:** "" + + + This can be set to the path of an additional settings file that is executed after the normal settings file. + + + .. function:: midline_stiff_percentage(float) **default value:** 0.15 @@ -1500,15 +1520,6 @@ TRex parameters -.. function:: huge_timestamp_seconds(double) - - **default value:** 0.2 - - - Defaults to 0.5s (500ms), can be set to any value that should be recognized as being huge. - - - .. function:: auto_no_tracking_data(bool) **default value:** false @@ -1583,34 +1594,6 @@ TRex parameters -.. function:: blob_split_global_shrink_limit(float) - - **default value:** 0.2 - - - The minimum percentage of the minimum in `blob_size_ranges`, that a blob is allowed to be reduced to during splitting. If this value is set too low, the program might start recognizing parts of individual as other individual too quickly. - - .. seealso:: :func:`blob_size_ranges`, - - -.. function:: blobs_per_thread(float) - - **default value:** 150 - - - Number of blobs for which properties will be calculated per thread. - - - -.. function:: gui_heatmap_smooth(double) - - **default value:** 0 - - - Value between 0 and 1, think of as `gui_heatmap_smooth` times video width, indicating the maximum upscaled size of the heatmaps shown in the tracker. Makes them prettier. - - - .. function:: auto_minmax_size(bool) **default value:** false @@ -1639,15 +1622,6 @@ TRex parameters -.. function:: track_do_history_split(bool) - - **default value:** true - - - If disabled, blobs will not be split automatically in order to separate overlapping individuals. This usually happens based on their history. - - - .. function:: outline_smooth_samples(uchar) **default value:** 4 @@ -1667,161 +1641,165 @@ TRex parameters .. seealso:: :func:`recognition_border`, -.. function:: debug_recognition_output_all_methods(bool) +.. function:: auto_no_memory_stats(bool) - **default value:** false + **default value:** true - If set to true, a complete training will attempt to output all images for each identity with all available normalization methods. + If set to true, no memory statistics will be saved on auto_quit. -.. function:: output_frame_window(int) +.. function:: track_max_reassign_time(float) - **default value:** 100 + **default value:** 0.5 - If an individual is selected during CSV output, use these number of frames around it (or -1 for all frames). + Distance in time (seconds) where the matcher will stop trying to reassign an individual based on previous position. After this time runs out, depending on the settings, the tracker will try to find it based on other criteria, or generate a new individual. -.. function:: gui_background_color(color) +.. function:: build_is_debug(string) - **default value:** [0,0,0,150] + **default value:** "debug" - Values < 255 will make the background more transparent in standard view. This might be useful with very bright backgrounds. + If built in debug mode, this will show 'debug'. -.. function:: recognition_border_shrink_percent(float) +.. function:: ffmpeg_path(path) - **default value:** 0.3 + **default value:** "" - The amount by which the recognition border is shrunk after generating it (roughly and depends on the method). + Path to an ffmpeg executable file. This is used for converting videos after recording them (from the GUI). It is not a critical component of the software, but mostly for convenience. -.. function:: match_mode(matching_mode_t) +.. function:: recognition_normalization(recognition_normalization_t) - **default value:** accurate + **default value:** posture **possible values:** - - `accurate`: Maximizes the probability sum by assigning (or potentially not assigning) individuals to objects in the frame. This returns the correct solution, but might take long for high quantities of individuals. - - `approximate`: Simply assigns the highest probability edges (blob to individual) to all individuals - first come, first serve. Parameters have to be set very strictly (especially speed) in order to have as few objects to choose from as possible and limit the error. - - `hungarian`: The hungarian algorithm (as implemented in O(n^3) by Mattias Andrée `https://github.com/maandree/hungarian-algorithm-n3`). - - `benchmark`: Runs all algorithms and pits them against each other, outputting statistics every few frames. + - `none`: No normalization. Images will only be cropped out and used as-is. + - `moments`: Images will be cropped out and aligned as in idtracker.ai using the main axis calculated using `image moments`. + - `posture`: Images will be cropped out and rotated so that the head will be fixed in one position and only the tail moves. + - `legacy`: Images will be aligned parallel to the x axis. - Changes the default algorithm to be used for matching blobs in one frame to blobs in the next frame. The accurate algorithm performs best, but also scales less well for more individuals than the approximate one. However, if it is too slow (temporarily) in a few frames, the program falls back to using the approximate one that doesnt slow down. + This enables or disable normalizing the images before training. If set to `none`, the images will be sent to the GPU raw - they will only be cropped out. Otherwise they will be normalized based on head orientation (posture) or the main axis calculated using `image moments`. + .. seealso:: :func:`none`, :func:`image moments`, -.. function:: app_name(string) +.. function:: tracklet_restore_split_blobs(bool) - **default value:** "TRex" + **default value:** true - Name of the application. + If enabled, all exported tracklet images are checked for missing pixels. When a blob is too close to another blob, parts of the other blob might be erased so the individuals can be told apart. If enabled, another mask will be saved, that contains only the blob in focus, without the rest-pixels. -.. function:: log_file(path) +.. function:: output_prefix(string) **default value:** "" - Set this to a path you want to save the log file to. + A prefix that is prepended to all output files (csv/npz). -.. function:: auto_apply(bool) +.. function:: video_length(ulong) - **default value:** false + **default value:** 0 - If set to true, the application will automatically apply the network with existing weights once the analysis is done. It will then automatically correct and reanalyse the video. + The length of the video in frames -.. function:: build(string) +.. function:: log_file(path) **default value:** "" - Current build version + Set this to a path you want to save the log file to. -.. function:: auto_no_memory_stats(bool) +.. function:: auto_apply(bool) - **default value:** true + **default value:** false - If set to true, no memory statistics will be saved on auto_quit. + If set to true, the application will automatically apply the network with existing weights once the analysis is done. It will then automatically correct and reanalyse the video. -.. function:: track_max_reassign_time(float) +.. function:: build(string) - **default value:** 0.5 + **default value:** "" - Distance in time (seconds) where the matcher will stop trying to reassign an individual based on previous position. After this time runs out, depending on the settings, the tracker will try to find it based on other criteria, or generate a new individual. + Current build version -.. function:: ffmpeg_path(path) +.. function:: web_time_threshold(float) - **default value:** "" + **default value:** 0.05 - Path to an ffmpeg executable file. This is used for converting videos after recording them (from the GUI). It is not a critical component of the software, but mostly for convenience. + Maximum refresh rate in seconds for the web interface. -.. function:: recognition_normalization(recognition_normalization_t) +.. function:: midline_walk_offset(float) - **default value:** posture + **default value:** 0.025 - **possible values:** - - `none`: No normalization. Images will only be cropped out and used as-is. - - `moments`: Images will be cropped out and aligned as in idtracker.ai using the main axis calculated using `image moments`. - - `posture`: Images will be cropped out and rotated so that the head will be fixed in one position and only the tail moves. - - `legacy`: Images will be aligned parallel to the x axis. - This enables or disable normalizing the images before training. If set to `none`, the images will be sent to the GPU raw - they will only be cropped out. Otherwise they will be normalized based on head orientation (posture) or the main axis calculated using `image moments`. + This percentage of the number of outline points is the amount of points that the midline-algorithm is allowed to move left and right upon each step. Higher numbers will make midlines more straight, especially when extremities are present (that need to be skipped over), but higher numbers will also potentially decrease accuracy for less detailed objects. - .. seealso:: :func:`none`, :func:`image moments`, +.. function:: gui_show_histograms(bool) -.. function:: tracklet_restore_split_blobs(bool) + **default value:** false + + + Equivalent to the checkbox visible in GUI on the bottom-left. + + + +.. function:: track_do_history_split(bool) **default value:** true - If enabled, all exported tracklet images are checked for missing pixels. When a blob is too close to another blob, parts of the other blob might be erased so the individuals can be told apart. If enabled, another mask will be saved, that contains only the blob in focus, without the rest-pixels. + If disabled, blobs will not be split automatically in order to separate overlapping individuals. This usually happens based on their history. -.. function:: output_prefix(string) +.. function:: output_image_per_tracklet(bool) - **default value:** "" + **default value:** false - A prefix that is prepended to all output files (csv/npz). + If set to true, the program will output one median image per tracklet (time-series segment) and save it alongside the npz/csv files. -.. function:: video_length(ulong) +.. function:: outline_curvature_range_ratio(float) - **default value:** 0 + **default value:** 0.03 - The length of the video in frames + Determines the ratio between number of outline points and distance used to calculate its curvature. Program will look at index +- `ratio * size()` and calculate the distance between these points (see posture window red/green color). + .. seealso:: :func:`ratio * size()`, .. function:: gui_show_midline(bool) @@ -1865,6 +1843,66 @@ TRex parameters +.. function:: debug_recognition_output_all_methods(bool) + + **default value:** false + + + If set to true, a complete training will attempt to output all images for each identity with all available normalization methods. + + + +.. function:: output_frame_window(int) + + **default value:** 100 + + + If an individual is selected during CSV output, use these number of frames around it (or -1 for all frames). + + + +.. function:: gui_background_color(color) + + **default value:** [0,0,0,150] + + + Values < 255 will make the background more transparent in standard view. This might be useful with very bright backgrounds. + + + +.. function:: recognition_border_shrink_percent(float) + + **default value:** 0.3 + + + The amount by which the recognition border is shrunk after generating it (roughly and depends on the method). + + + +.. function:: match_mode(matching_mode_t) + + **default value:** accurate + + **possible values:** + - `accurate`: Maximizes the probability sum by assigning (or potentially not assigning) individuals to objects in the frame. This returns the correct solution, but might take long for high quantities of individuals. + - `approximate`: Simply assigns the highest probability edges (blob to individual) to all individuals - first come, first serve. Parameters have to be set very strictly (especially speed) in order to have as few objects to choose from as possible and limit the error. + - `hungarian`: The hungarian algorithm (as implemented in O(n^3) by Mattias Andrée `https://github.com/maandree/hungarian-algorithm-n3`). + - `benchmark`: Runs all algorithms and pits them against each other, outputting statistics every few frames. + + Changes the default algorithm to be used for matching blobs in one frame to blobs in the next frame. The accurate algorithm performs best, but also scales less well for more individuals than the approximate one. However, if it is too slow (temporarily) in a few frames, the program falls back to using the approximate one that doesnt slow down. + + + + +.. function:: app_name(string) + + **default value:** "TRex" + + + Name of the application. + + + .. function:: gui_heatmap_resolution(uint) **default value:** 75 @@ -1911,16 +1949,6 @@ TRex parameters -.. function:: track_whitelist(array<array<vec>>) - - **default value:** [] - - - If this is not empty, objects within the given rectangles or polygons (>= 3 points) [[x0,y0],[x1,y1](, ...)], ...] will be the only objects being tracked. (overwrites `track_blacklist`) - - .. seealso:: :func:`track_blacklist`, - - .. function:: calculate_posture(bool) **default value:** true