From 1dce1aacb0654a4de94cb14b4552799741d57fc5 Mon Sep 17 00:00:00 2001
From: Tristan Walter <twalter@orn.mpg.de>
Date: Fri, 16 Oct 2020 17:21:31 +0200
Subject: [PATCH] * use better algorithm for finding the correct blobs with
tracklet images * update docs
---
Application/src/tracker/tracking/Export.cpp | 16 ++++-
docs/contents.rst | 4 +-
docs/examples.rst | 69 +++++++++++++++++++++
docs/faq.rst | 35 +++++++++++
docs/formats.rst | 10 +++
docs/run.rst | 40 +-----------
6 files changed, 134 insertions(+), 40 deletions(-)
create mode 100644 docs/examples.rst
create mode 100644 docs/faq.rst
diff --git a/Application/src/tracker/tracking/Export.cpp b/Application/src/tracker/tracking/Export.cpp
index ab15f66..72dc304 100644
--- a/Application/src/tracker/tracking/Export.cpp
+++ b/Application/src/tracker/tracking/Export.cpp
@@ -758,6 +758,14 @@ void export_data(Tracker& tracker, long_t fdx, const Rangel& range) {
Tracker::instance()->preprocess_frame(obj, active, &_blob_thread_pool);
}
+ std::map<uint32_t, pv::BlobPtr> blob_to_id;
+ for(auto &blob : obj.blobs)
+ blob_to_id[blob->blob_id()] = blob;
+ for(auto &blob : obj.filtered_out)
+ blob_to_id[blob->blob_id()] = blob;
+ for(auto &blob : obj.original_blobs)
+ blob_to_id[blob->blob_id()] = blob;
+
for(auto && [id, data] : vec) {
struct ImagePosition {
std::unique_ptr<Image> image;
@@ -765,7 +773,11 @@ void export_data(Tracker& tracker, long_t fdx, const Rangel& range) {
pv::BlobPtr blob;
} reduced, full;
- for (auto b : obj.blobs) {
+ reduced.blob = Tracker::find_blob_noisy(blob_to_id, data.blob.blob_id, data.blob.parent_id, Bounds(), data.frame);
+ if(data.blob.org_id != -1) {
+ full.blob = Tracker::find_blob_noisy(blob_to_id, data.blob.org_id, data.blob.parent_id, Bounds(), data.frame);
+ }
+ /*for (auto b : obj.blobs) {
if(data.blob.org_id != -1) {
if(b->blob_id() == (uint32_t)data.blob.org_id) {
//Debug("%ld == %d", data.blob.org_id, b->blob_id());
@@ -778,7 +790,7 @@ void export_data(Tracker& tracker, long_t fdx, const Rangel& range) {
if((reduced.blob && full.blob) || (reduced.blob && data.blob.org_id == -1))
break;
- }
+ }*/
if(data.blob.org_id != -1 && !full.blob)//if(!reduced.blob)
{
diff --git a/docs/contents.rst b/docs/contents.rst
index d3d86d8..bd2289f 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -40,6 +40,8 @@ Whereas other use-cases are:
install
run
+ examples
formats
parameters_trex
- parameters_tgrabs
\ No newline at end of file
+ parameters_tgrabs
+ faq
\ No newline at end of file
diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000..3bdc803
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,69 @@
+.. include:: names.rst
+
+.. toctree::
+ :maxdepth: 2
+
+Examples
+########
+
+This section contains an assortment of common usage examples, taken from the real world. We will explain each example shortly and move on quickly. If certain details are unclear, :doc:`parameters_trex` or :doc:`parameters_tgrabs` might help!
+
+TGrabs
+******
+
+Converting videos
+=================
+
+Just open a movie file and convert it to the PV format (it will be saved to the default output location, and named after the input file). Just for fun, we also set a different (higher) threshold::
+
+ tgrabs -i <MOVIE> -threshold 35
+
+We can switch to a different background subtraction method, by using::
+
+ tgrabs -i <MOVIE> -threshold 35 -averaging_method mode -reset_average
+
+The background will be saved to a png file in the output folder. You can edit it manually, too (until you use use ``reset_average``).
+
+Record using a Basler camera
+============================
+
+TRex
+****
+
+.. NOTE::
+ Keep in mind that all parameters specified here in the the command-line can also be accessed if you're already within the graphical user interface.
+
+Open a video::
+
+ trex -i <VIDEO>
+
+*Hey, but I know how many individuals I have!* If you do, you should always specify (although |trex| tries to find it out by itself)::
+
+ trex -i <VIDEO> -track_max_individuals 8
+
+Open a video, track it using the parameters set in command-line and the settings file at path <SETTINGS>, and save all selected output options to ``/data/<VIDEO_NAME>_fish*.npz``, etc.::
+
+ trex -i <VIDEO> -s <SETTINGS> -auto_quit
+
+Same as above, but don't save tracking data (only posture and ``.results``)::
+
+ trex -i <VIDEO> -s <SETTINGS> -auto_quit -auto_no_tracking_data
+
+Launch the tracking software, track it and automatically correct it using the visual identification. For this, you always have to specify the number of individuals, either via the command-line or in ``<VIDEO_NAME>.settings``::
+
+ trex -i <VIDEO> -track_max_individuals 10 -auto_train
+
+Same as above, but also save stuff and quit (e.g. for batch processing)::
+
+ trex -i <VIDEO> -track_max_individuals 10 -auto_train -auto_quit
+
+Don't show the graphical user-interface (really only useful when combined with ``auto_`` options or some serious terminal-based hacking). It can be quit using CTRL+C (or whatever is the equivalent in your system/terminal)::
+
+ trex -i <VIDEO> -nowindow
+
+If your desired output are images of each individual, you can combine either of the options above and set ``output_image_per_tracklet`` to ``true`` and ``tracklet_max_images`` to ``0`` (which means 'no limit'). We will output only tracklet images, no tracking data/results files::
+
+ trex -i <VIDEO> -output_image_per_tracklet -tracklet_max_images 0 \
+ -tracklet_normalize_orientation false -auto_quit -auto_no_results \
+ -auto_no_tracking_data
+
diff --git a/docs/faq.rst b/docs/faq.rst
new file mode 100644
index 0000000..1807fc0
--- /dev/null
+++ b/docs/faq.rst
@@ -0,0 +1,35 @@
+.. include:: names.rst
+
+.. toctree::
+ :maxdepth: 2
+
+Frequently asked questions and solutions to weird problems
+==========================================================
+
+I am using Windows and Python cannot be initialized successfully!
+ If you compiled or installed |trex| in a conda environment and it is having trouble finding the necessary files, you can try to help it by editing the default.settings file inside the application folder (be careful if you're compiling the program on your own, the one in the build folder gets replaced by the one in the folder ``[root]/Application/default.settings`` after every build that altered anything). Just put a ``python_path = "C:\Users\[USERNAME]\Anaconda3\envs\[ENVNAME]"`` inside it and try starting again! Otherwise, you can be more savage and set the ``PYTHONHOME`` variable to the same folder and add it to ``PATH``, too (this breaks other anaconda stuff most likely).
+
+Segmentation/objects barely visible or too large!
+ Is the background image good enough (if you're using background subtraction), e.g. are there artifacts from individuals visible in the background, or does the background change during the video?
+ If the background is dynamic, you might have to disable subtraction by setting :func:`enable_difference` to false, and adjusting :func:`threshold` to a cut-off greyscale value. Otherwise, consider using a different :func:`averaging_method`. For example, max/mode are good for white backgrounds and short videos, or barely moving individuals.
+ Is there a lot of magenta-colored noise outside of objects?
+ Increase :func:`threshold` during recording/conversion.
+ Objects are too small?
+ Decrease :func:`threshold` during recording/conversion.
+
+Trajectories jump around a lot for no particular reason!
+ Changing :func:`track_max_speed` might help to mitigate this problem. Generally this can be the symptom of many different problems that lead to individuals being lost: size, speed, visibility issues, etc.: Sometimes individuals are lost because they are moving too fast (faster than the maximally allowed speed), or because they are expected to move much faster. Try lowering or increasing that limit. To get a hint at which speed to set, open up |trex|, track a few frames and select an individual - if there are consecutive frames for that individual, it will display a cm/s speed in the top-left overlay.
+
+I set :func:`track_max_individuals` to zero, but it still does not track all individuals!
+ Probably what's happening is that you have not created a ``.settings`` file for the given video yet (or not in the right folder). Try that, and then attach the command-line option again.
+
+|trex| is really **laggy** and frequently complains about **too many combinations**!
+ Pause the analysis (``,`` key, this may take a few seconds). The matching algorithm has diffculty separating individuals into distinct cliques of neighboring individuals, or there are simply too many of them. This could be because your video contains too many trackable objects and no limit on the number of individuals has been set (:func:`track_max_individuals`), or there are significant time-jumps in the video. If the number of individuals should be much lower than detected, check your :func:`track_threshold`/:func:`blob_size_ranges` settings. It is advisable to start |trex| with likely parameters, or pausing analysis to change parameters. Otherwise, if that does not fix anything, check your settings for :func:`track_max_speed`, which controls the size of the neighbourhood to be considered during matching, and reduce it until there are no further warnings.
+
+|grabs| does not quit and only shows "[...] not properly closed [...]"!
+ You may have to forcibly quit the application, either using a task manager, or by finding and manually ending its process::
+
+ ps aux | grep tgrabs
+
+I have attached my Basler camera, and now |grabs| is stuck initializing the camera!
+ Most likely the camera driver crashed. Try restarting your computer to fix it.
diff --git a/docs/formats.rst b/docs/formats.rst
index 18136c0..2b6e7ed 100644
--- a/docs/formats.rst
+++ b/docs/formats.rst
@@ -37,7 +37,17 @@ If one metric (such as anything posture-related) is not available in a frame --
Posture
-------
+(todo)
+Tracklet images
+---------------
+
+(todo)
+
+Visual fields
+-------------
+
+(todo)
PreprocessedVideo (pv)
**********************
diff --git a/docs/run.rst b/docs/run.rst
index 33225a4..3274eed 100644
--- a/docs/run.rst
+++ b/docs/run.rst
@@ -9,6 +9,8 @@ Basic usage
|trex| can be launched simply by double-clicking it, or launching it from the command-line without parameters, which will show a file opening dialog. Its younger sibling, |grabs|, also offers a graphical user interface, but can only be started from the terminal at the moment (we will be working on changing that, and also potentially integrating it completely with |trex|). The following sections address the issue of directly providing parameters using the command-line for both softwares (e.g. in a batch processing, or generally a more command-line affine use-case). If you're launching |trex| by double-clicking it (or using voice commands), most parameters (except system-variables) can be adjusted after loading a video.
+This page is a reference for some commonly used parameters of our software. Some common real-life usage examples can be found at :doc:`examples`.
+
Basic principles
----------------
@@ -16,11 +18,7 @@ Both |grabs| and |trex| offer many parameters that can be set by users. However,
If there is no problem, do not change parameters.
-Otherwise, if your problem cannot be solved by repeatedly mashing the same sequence of buttons (but with an increasingly stern expression on your face), please consider the list of probable solutions in (`Frequently asked questions and solutions to weird problems`_).
-
-.. NOTE::
-
- Explicitly discouraging this specific kind of problem-solving is motivated by the results of informal (but extensive) user-studies conducted in the last four years.
+Otherwise, if your problem cannot be solved by repeatedly mashing the same sequence of buttons (but with an increasingly stern expression on your face), please consider the list of things that happen frequently in (:doc:`faq`).
Parameters are either changed directly as part of the command-line (using ``-PARAMETER VALUE``), in settings files or from within the graphical user interface (or magically). Settings files are called [VIDEONAME].settings, and located either in the same folder as the video, or in the output folder (``~/Videos`` by default, or set using the command-line option ``-d /folder/path``). These settings files are automatically loaded along with the video. Settings that were changed by command-line parameters can be saved by pressing ``menu -> save config``.
@@ -168,35 +166,3 @@ Batch processing support
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
-
-
-Frequently asked questions and solutions to weird problems
-==========================================================
-
-I am using Windows and Python cannot be initialized successfully!
- If you compiled or installed |trex| in a conda environment and it is having trouble finding the necessary files, you can try to help it by editing the default.settings file inside the application folder (be careful if you're compiling the program on your own, the one in the build folder gets replaced by the one in the folder ``[root]/Application/default.settings`` after every build that altered anything). Just put a ``python_path = "C:\Users\[USERNAME]\Anaconda3\envs\[ENVNAME]"`` inside it and try starting again! Otherwise, you can be more savage and set the ``PYTHONHOME`` variable to the same folder and add it to ``PATH``, too (this breaks other anaconda stuff most likely).
-
-Segmentation/objects barely visible or too large!
- Is the background image good enough (if you're using background subtraction), e.g. are there artifacts from individuals visible in the background, or does the background change during the video?
- If the background is dynamic, you might have to disable subtraction by setting :func:`enable_difference` to false, and adjusting :func:`threshold` to a cut-off greyscale value. Otherwise, consider using a different :func:`averaging_method`. For example, max/mode are good for white backgrounds and short videos, or barely moving individuals.
- Is there a lot of magenta-colored noise outside of objects?
- Increase :func:`threshold` during recording/conversion.
- Objects are too small?
- Decrease :func:`threshold` during recording/conversion.
-
-Trajectories jump around a lot for no particular reason!
- Changing :func:`track_max_speed` might help to mitigate this problem. Generally this can be the symptom of many different problems that lead to individuals being lost: size, speed, visibility issues, etc.: Sometimes individuals are lost because they are moving too fast (faster than the maximally allowed speed), or because they are expected to move much faster. Try lowering or increasing that limit. To get a hint at which speed to set, open up |trex|, track a few frames and select an individual - if there are consecutive frames for that individual, it will display a cm/s speed in the top-left overlay.
-
-I set :func:`track_max_individuals` to zero, but it still does not track all individuals!
- Probably what's happening is that you have not created a ``.settings`` file for the given video yet (or not in the right folder). Try that, and then attach the command-line option again.
-
-|trex| is really **laggy** and frequently complains about **too many combinations**!
- Pause the analysis (``,`` key, this may take a few seconds). The matching algorithm has diffculty separating individuals into distinct cliques of neighboring individuals, or there are simply too many of them. This could be because your video contains too many trackable objects and no limit on the number of individuals has been set (:func:`track_max_individuals`), or there are significant time-jumps in the video. If the number of individuals should be much lower than detected, check your :func:`track_threshold`/:func:`blob_size_ranges` settings. It is advisable to start |trex| with likely parameters, or pausing analysis to change parameters. Otherwise, if that does not fix anything, check your settings for :func:`track_max_speed`, which controls the size of the neighbourhood to be considered during matching, and reduce it until there are no further warnings.
-
-|grabs| does not quit and only shows "[...] not properly closed [...]"!
- You may have to forcibly quit the application, either using a task manager, or by finding and manually ending its process::
-
- ps aux | grep tgrabs
-
-I have attached my Basler camera, and now |grabs| is stuck initializing the camera!
- Most likely the camera driver crashed. Try restarting your computer to fix it.
\ No newline at end of file
--
GitLab