diff --git a/Application/src/tracker/gui/IdentityHeatmap.cpp b/Application/src/tracker/gui/IdentityHeatmap.cpp
index 96c8065574c19386eda887a82df13e05af07da11..736258fb1f7ccb628b0366155fc2935fc6a63c13 100644
--- a/Application/src/tracker/gui/IdentityHeatmap.cpp
+++ b/Application/src/tracker/gui/IdentityHeatmap.cpp
@@ -562,7 +562,7 @@ bool HeatmapController::update_variables() {
set_content_changed(true);
}
- const uint32_t res = max(2u, min((uint32_t)(Tracker::average().bounds().size().min() * 0.5), SETTING(gui_heatmap_resolution).value<uint32_t>()));
+ const uint32_t res = max(2u, min((uint32_t)(Tracker::average().bounds().size().min() * 0.5), SETTING(heatmap_resolution).value<uint32_t>()));
if(res != uniform_grid_cell_size) {
uniform_grid_cell_size = res;
@@ -578,29 +578,29 @@ bool HeatmapController::update_variables() {
has_to_paint = true;
}
- const Range<double> custom_value_range = SETTING(gui_heatmap_value_range).value<Range<double>>();
+ const Range<double> custom_value_range = SETTING(heatmap_value_range).value<Range<double>>();
if(custom_value_range != custom_heatmap_value_range) {
custom_heatmap_value_range = custom_value_range;
has_to_paint = true;
}
- const double gui_heatmap_smooth = max(0, min(1, SETTING(gui_heatmap_smooth).value<double>()));
- if(smooth_heatmap_factor != gui_heatmap_smooth) {
- smooth_heatmap_factor = gui_heatmap_smooth;
+ const double heatmap_smooth = max(0, min(1, SETTING(heatmap_smooth).value<double>()));
+ if(smooth_heatmap_factor != heatmap_smooth) {
+ smooth_heatmap_factor = heatmap_smooth;
has_to_paint = true;
}
- //SETTING(gui_heatmap_resolution) = uniform_grid_cell_size + 1;
+ //SETTING(heatmap_resolution) = uniform_grid_cell_size + 1;
- auto norm = SETTING(gui_heatmap_normalization).value<default_config::heatmap_normalization_t::Class>();
+ auto norm = SETTING(heatmap_normalization).value<default_config::heatmap_normalization_t::Class>();
if(norm != _normalization) {
_normalization = norm;
has_to_paint = true;
}
long_t context;
- if(SETTING(gui_heatmap_dynamic)) {
- context = max(1, (long_t)SETTING(gui_heatmap_frames).value<uint32_t>());
+ if(SETTING(heatmap_dynamic)) {
+ context = max(1, (long_t)SETTING(heatmap_frames).value<uint32_t>());
} else {
context = -1;
@@ -612,7 +612,7 @@ bool HeatmapController::update_variables() {
_frame_context = context;
}
- std::string source = SETTING(gui_heatmap_source);
+ std::string source = SETTING(heatmap_source);
if(_original_source != source) {
_original_source = source;
diff --git a/Application/src/tracker/misc/default_config.cpp b/Application/src/tracker/misc/default_config.cpp
index 71934ae2251c0b5e830705c6cd0b66b74f7e87aa..7f1164696d58b14dbefd720607fd6c16b81d6a29 100644
--- a/Application/src/tracker/misc/default_config.cpp
+++ b/Application/src/tracker/misc/default_config.cpp
@@ -291,13 +291,13 @@ file::Path conda_environment_path() {
CONFIG("gui_faded_brightness", uchar(255), "The alpha value of tracking-related elements when timeline is hidden (0-255).");
CONFIG("gui_equalize_blob_histograms", true, "Equalize histograms of blobs wihtin videos (makes them more visible).");
CONFIG("gui_show_heatmap", false, "Showing a heatmap per identity, normalized by maximum samples per grid-cell.");
- CONFIG("gui_heatmap_value_range", Range<double>(-1, -1), "Give a custom value range that is used to normalize heatmap cell values.");
- CONFIG("gui_heatmap_smooth", double(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.");
- CONFIG("gui_heatmap_normalization", heatmap_normalization_t::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.");
- CONFIG("gui_heatmap_frames", uint32_t(0), "If `gui_heatmap_dynamic` is enabled, this variable determines the range of frames that are considered. If set to 0, all frames up to the current frame are considered. Otherwise, this number determines the number of frames previous to the current frame that are considered.");
- CONFIG("gui_heatmap_dynamic", false, "If enabled the heatmap will only show frames before the frame currently displayed in the graphical user interface.");
- CONFIG("gui_heatmap_resolution", uint32_t(75), "Square resolution of individual heatmaps displayed with `gui_show_heatmap`. Will generate a square grid, each cell with dimensions (video_width / N, video_height / N), and sort all positions of each identity into it.");
- CONFIG("gui_heatmap_source", std::string(), "If empty, the source will simply be an individuals identity. Otherwise, information from export data sources will be used.");
+ CONFIG("heatmap_value_range", Range<double>(-1, -1), "Give a custom value range that is used to normalize heatmap cell values.");
+ CONFIG("heatmap_smooth", double(0.05), "Value between 0 and 1, think of as `heatmap_smooth` times video width, indicating the maximum upscaled size of the heatmaps shown in the tracker. Makes them prettier, but maybe much slower.");
+ CONFIG("heatmap_normalization", heatmap_normalization_t::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.");
+ CONFIG("heatmap_frames", uint32_t(0), "If `heatmap_dynamic` is enabled, this variable determines the range of frames that are considered. If set to 0, all frames up to the current frame are considered. Otherwise, this number determines the number of frames previous to the current frame that are considered.");
+ CONFIG("heatmap_dynamic", false, "If enabled the heatmap will only show frames before the frame currently displayed in the graphical user interface.");
+ CONFIG("heatmap_resolution", uint32_t(64), "Square resolution of individual heatmaps displayed with `gui_show_heatmap`. Will generate a square grid, each cell with dimensions (video_width / N, video_height / N), and sort all positions of each identity into it.");
+ CONFIG("heatmap_source", std::string(), "If empty, the source will simply be an individuals identity. Otherwise, information from export data sources will be used.");
CONFIG("gui_mode", gui::mode_t::tracking, "The currently used display mode for the GUI.");
CONFIG("panic_button", int(0), "42");
CONFIG("gui_run", false, "When set to true, the GUI starts playing back the video and stops once it reaches the end, or is set to false.");
diff --git a/docs/contents.rst b/docs/contents.rst
index bb5a2c8f6089e8e1cbb276e93bd970235039fb8b..d3d86d8575ca7cdba5378ba7d5855de9a3f100c4 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -3,6 +3,9 @@
Welcome to TRex's documentation!
================================
+.. NOTE::
+ This page (and the github repository at https://github.com/mooch443/trex) will be updated frequently at the moment, since |trex| is still in active development. If you find any issues, please report them using the github issue tracker!
+
|trex| is a tracking software designed to track and identify individuals and other moving entities using computer vision and machine learning. The work-load is split into two (not entirely separate) tools:
* **TGrabs**: Record or convert existing videos, perform live-tracking and closed-loop experiments
@@ -16,6 +19,9 @@ Welcome to TRex's documentation!
<source src="composite_tracking_video.mov" type='video/mp4; codecs="h264"' />
</video>
+Workflow
+--------
+
|grabs| always has to be used first. |trex| is optional in some cases. Use-cases where |trex| is not required include:
* *Just give me tracks*: The user has a video and wants positional, or posture-related data for the individuals seen in the video. Maintaining identities is not required.
diff --git a/docs/run.rst b/docs/run.rst
index 93d1c04840eb03c3912c2ce9f4052c286dd18ac7..b5029a51bb65b3faae9216564d0894215248fc52 100644
--- a/docs/run.rst
+++ b/docs/run.rst
@@ -51,6 +51,11 @@ If there are ``[XXXXX].npz`` files (named exactly like the video files but with
- 'frame_time': an array of N doubles for all N frames in the video segment
- 'imgshape': a tuple of integers (width, height) of the video
+
+Other useful options are::
+
+ - 'meta_real_width': The width of what is seen in the video in cms. This is used to convert px -> cm internally, and is saved as meta information inside the .pv file.
+ - 'meta_species': Species (meta-information, entirely optional)
Running TRex
------------
@@ -63,15 +68,77 @@ The tracker only expects an input file::
Just like with |grabs|, you can attach any number of additional parameters to the command-line, simply using ``-PARAMETER VALUE`` (see :doc:`parameters_trex`).
+Tools
+-----
+
+Another tool is included, called ``pvinfo``, which can be used programmatically (e.g. in jupyter notebooks) to retrieve information about converted videos and the settings used to track them. The usual way to make use of it within python is::
+
+ def get_parameter(video, parameter, root = "", prefix = "", info_path = "/path/to/pvinfo"):
+ """Uses the pvinfo utility to retrieve information about tracked videos.
+ This information is usually saved in the .pv files / .settings / .results files.
+ The pvinfo utility will emulate a call to TRex + loading existing .results files
+ and settings files in the same order.
+
+ Parameters
+ ----------
+ video : str
+ Name of the video, or absolute path to the video
+ parameter : str
+ Name of the parameter to retrieve (see https://trex.run/docs/parameters_trex.html)
+ root : str, optional
+ Either empty (default), or path to the folder the video is in
+ prefix : str, optional
+ Either empty (default), or name of the output_prefix to be used
+ info_path : str
+ Absolute path to the pvinfo utility executable
+
+ Returns
+ -------
+ object
+ The return type is determined by the type of the parameter requested
+ """
+
+ from subprocess import Popen, PIPE
+ import ast
+
+ if type(info_path) == type(None):
+ process = Popen(["which", "tgrabs"], stdout=PIPE)
+ (output, err) = process.communicate()
+ exit_code = process.wait()
+ if exit_code != 0:
+ raise Exception("Cannot retrieve info path.")
+ info_path = output.decode("utf-8").split("=")[-1][1:-1]
+ info_path = info_path.split("/tgrabs")[0] + "/info"
+ print(info_path)
+
+ parameter_list = [info_path]
+ if root != "":
+ parameter_list += ["-d",root]
+ if prefix != "":
+ parameter_list += ["-p", prefix]
+
+ parameter_list += ["-i", video,"-quiet","-print_parameters","["+parameter+"]"]
+
+ process = Popen(parameter_list, stdout=PIPE)
+ (output, err) = process.communicate()
+ exit_code = process.wait()
+ if exit_code == 0:
+ return ast.literal_eval(output.decode("utf-8").split("=")[-1][1:-1])
+ raise Exception("Cannot retrieve "+parameter+" from "+video+": "+output.decode("utf-8")+" ("+str(exit_code)+") "+" ".join(parameter_list))
+
+But it has many other uses, too! For example, it can be used to save heatmap information that can be visualized in |trex| (but can not currently be saved directly from |trex| -> will be soon)::
+
+ pvinfo -i video -heatmap -heatmap_source SPEED -heatmap_resolution 128 -heatmap_frames 100 -heatmap_dynamic
+
Batch processing support
========================
|trex| and |grabs| both offer full batch processing support. All parameters that can be setup via the settings box (and even some that are read-only when the program is already started), can be appended to the command-line -- as mentioned above. For batch processing, special parameters are available::
- auto_quit # automatically saves all requested data to the output folder and quits the app
- auto_train # automatically attempts to train the visual identification if successfully tracked
- auto_apply # automatically attempts to load weights from a previous training and auto correct the video
- auto_no_results # do not save a .results file
+ auto_quit # automatically saves all requested data to the output folder and quits the app
+ auto_train # automatically attempts to train the visual identification if successfully tracked
+ auto_apply # automatically attempts to load weights from a previous training and auto correct the video
+ auto_no_results # do not save a .results file
auto_no_tracking_data # do not save the data/file_fishX.npz files
auto_no_memory_stats # (enabled by default) do not save memory statistics