3.1. Detection Parameters
The meteors detection chain is located here: ./bin/fmdt-detect
.
The following table summarizes the available parameters:
Argument |
Type |
Details |
---|---|---|
|
STRING |
See Section 3.1.2. |
|
INTEGER |
See Section 3.1.3. |
|
INTEGER |
See Section 3.1.4. |
|
INTEGER |
See Section 3.1.5. |
|
BOOLEAN |
See Section 3.1.6. |
|
INTEGER |
See Section 3.1.7. |
|
INTEGER |
See Section 3.1.8. |
|
STRING |
See Section 3.1.9. |
|
STRING |
See Section 3.1.10. |
|
INTEGER |
See Section 3.1.11. |
|
INTEGER |
See Section 3.1.12. |
|
STRING |
See Section 3.1.13. |
|
BOOLEAN |
See Section 3.1.14. |
|
BOOLEAN |
See Section 3.1.15. |
|
BOOLEAN |
See Section 3.1.16. |
|
INTEGER |
See Section 3.1.17. |
|
INTEGER |
See Section 3.1.18. |
|
INTEGER |
See Section 3.1.19. |
|
INTEGER |
See Section 3.1.20. |
|
INTEGER |
See Section 3.1.21. |
|
INTEGER |
See Section 3.1.22. |
|
FLOAT |
See Section 3.1.23. |
|
INTEGER |
See Section 3.1.24. |
|
INTEGER |
See Section 3.1.25. |
|
FLOAT |
See Section 3.1.26. |
|
INTEGER |
See Section 3.1.27. |
|
INTEGER |
See Section 3.1.28. |
|
INTEGER |
See Section 3.1.29. |
|
FLOAT |
See Section 3.1.30. |
|
FLOAT |
See Section 3.1.31. |
|
BOOLEAN |
See Section 3.1.32. |
|
STRING |
See Section 3.1.33. |
|
STRING |
See Section 3.1.34. |
|
STRING |
See Section 3.1.35. |
|
BOOLEAN |
See Section 3.1.36. |
|
BOOLEAN |
See Section 3.1.37. |
3.1.1. Standard Output
fmdt-detect
outputs a list of tracks. The tracks represent the detected
objects in the video sequence. Here is the template of the output text:
# -------||---------------------------||---------------------------||---------
# Track || Begin || End || Object
# -------||---------------------------||---------------------------||---------
# -------||---------|--------|--------||---------|--------|--------||---------
# Id || Frame # | x | y || Frame # | x | y || Type
# -------||---------|--------|--------||---------|--------|--------||---------
{tid} || {fbeg} | {xbeg} | {ybeg} || {fend} | {xend} | {yend} || {otype}
{tid}
: a positive integer (start from1
) value representing a unique track identifier,{fbeg}
: a positive integer value representing the first frame in the video sequence when the track is detected,{xbeg}
: a positive real value of the x-axis coordinate (beginning of the track),{ybeg}
: a positive real value of the y-axis coordinate (beginning of the track),{fend}
: a positive integer value representing the last frame in the video sequence when the track is detected,{xend}
: a positive real value of the x-axis coordinate (end of the track),{yend}
: a positive real value of the y-axis coordinate (end of the track),{otype}
: a string of the object type, can be:meteor
,star
ornoise
.
3.1.2. --vid-in-path
- Deprecated
--in-video
- Type
STRING
- Default
[empty]
- Example
--vid-in-path ~/Videos/meteors.mp4
Input video path (supports also a path to a sequence of images
path/basename_%05d.jpg
).
3.1.3. --vid-in-start
- Deprecated
--fra-start
- Type
INTEGER
- Default
0
- Example
--vid-in-start 12
First frame id (included) to start the detection in the video sequence.
3.1.4. --vid-in-stop
- Deprecated
--fra-end
- Type
INTEGER
- Default
0
- Example
--vid-in-stop 42
Last frame id (included) to stop the detection in the video sequence. If set to
0
, read entire video.
3.1.5. --vid-in-skip
- Deprecated
--fra-skip
- Type
INTEGER
- Default
0
- Example
--vid-in-skip 1
Number of frames to skip.
3.1.6. --vid-in-buff
- Deprecated
--video-buff
- Type
BOOLEAN
- Example
--vid-in-buff
Bufferize all the video in global memory before executing the chain.
3.1.7. --vid-in-loop
- Deprecated
--video-loop
- Type
INTEGER
- Default
1
- Example
--vid-in-loop 10
Number of times the video is read in loop.
3.1.8. --vid-in-threads
- Deprecated
--ffmpeg-threads
- Type
INTEGER
- Default
0
- Example
--vid-in-threads 1
Select the number of threads to use to decode video input (in ffmpeg
). If
set to 0
, ffmpeg
chooses the number of threads automatically.
3.1.9. --vid-in-dec
- Type
STRING
- Default
FFMPEG-IO
- Example
--vid-in-dec VCODECS-IO
Select the input video decoder interface. FFMPEG-IO
is based on the cmd line
ffmpeg
executable to exchange decoded frames over a system pipe.
VCODECS-IO
directly call the libav
.
Note
VCODECS-IO
works only if FMDT has been compiled with the CMake
-DFMDT_USE_VCIO=ON
option (see Section 2.2.1).
3.1.10. --ccl-impl
- Type
STRING
- Default
LSLH
- Example
--ccl-impl LSLH
Choose the LSL implementation. Can be LSLH
or LSLM
.
LSLH
is the implementation discribed in [LZ09] and LSLM
is the implementation discribed in [LHL20].
Note
LSLM
is only available if FMDT has been compiled with the CMake
-DFMDT_LSL_LINK=ON
option (see Section 2.2.1).
3.1.11. --ccl-hyst-lo
- Deprecated
--light-min
- Type
INTEGER
- Default
55
- Example
--ccl-hyst-lo 100
Minimum light intensity for hysteresis threshold (grayscale \([0;255]\)).
3.1.12. --ccl-hyst-hi
- Deprecated
--light-max
- Type
INTEGER
- Default
80
- Example
--ccl-hyst-hi 140
Maximum light intensity for hysteresis threshold (grayscale \([0;255]\)).
3.1.13. --ccl-fra-path
- Deprecated
--out-frames
- Type
STRING
- Default
[empty]
- Example
--ccl-fra-path ccl_fra/%05d.png
Path of the files for CC debug (path/cc_%05d.png
).
3.1.14. --ccl-fra-id
- Deprecated
--show-id
- Type
BOOLEAN
- Example
--ccl-fra-id
Show the RoI/CC ids on the output frames (to combine with --ccl-fra-path
parameter). Requires to link with OpenCV library (-DFMDT_OPENCV_LINK
CMake
option, see Section 2.2.1).
3.1.15. --cca-mag
- Type
BOOLEAN
- Default
[empty]
- Example
--cca-mag
Enable the computation of two news features in the CCA: the magnitude and the counter of saturated pixels (to be combined with the --log-path option).
3.1.16. --cca-ell
- Type
BOOLEAN
- Default
[empty]
- Example
--cca-ell
Enable the computation of two news features in the CCA: a
the semi-major
axis of an ellipse and b
the semi-minor axis of an ellipse. This option
has to be combined with the --log-path option.
3.1.17. --cca-roi-max1
- Type
INTEGER
- Default
65535
- Example
--cca-roi-max1 10000
Maximum number of RoIs before hysteresis threshold. Allow to manage the memory footprint of the program. The Smaller the maximum number of RoIs, the smaller the memory footprint.
3.1.18. --cca-roi-max2
- Type
INTEGER
- Default
400
- Example
--cca-roi-max2 200
Maximum number of RoIs after hysteresis threshold. Allow to manage the memory footprint of the program. The Smaller the maximum number of RoIs, the smaller the memory footprint.
3.1.19. --mrp-s-min
- Deprecated
--surface-min
- Type
INTEGER
- Default
3
- Example
--mrp-s-min 5
Minimum surface of the CCs in pixels.
3.1.20. --mrp-s-max
- Deprecated
--surface-max
- Type
INTEGER
- Default
1000
- Example
--mrp-s-max 50
Maximum surface of the CCs in pixels.
3.1.21. --knn-k
- Deprecated
-k
- Type
INTEGER
- Default
3
- Example
--knn-k 5
Maximum number of neighbors considered in the k-NN algorithm.
3.1.22. --knn-d
- Deprecated
--max-dist
- Type
INTEGER
- Default
10
- Example
--knn-d 25
Maximum distance in pixels between two images (k-NN algorithm).
3.1.23. --knn-s
- Deprecated
--min-ratio-s
- Type
FLOAT
- Default
0.125
- Example
--knn-s 0.0
Minimum surface ratio to match two CCs in k-NN (0
matches alls, 1
matches nothing). This parameter is also used for extrapolation in the tracking.
3.1.24. --trk-ext-d
- Deprecated
--r-extrapol
- Type
INTEGER
- Default
5
- Example
--trk-ext-d 25
Search radius in pixels for CC extrapolation (piece-wise tracking).
3.1.25. --trk-ext-o
- Deprecated
--extrapol-orde
- Type
INTEGER
- Default
3
- Example
--trk-ext-o 1
Maximum number of frames to extrapolate for lost objects (linear extrapolation).
3.1.26. --trk-angle
- Deprecated
--angle-max
- Type
FLOAT
- Default
20.0
- Example
--trk-angle 35.0
Tracking max angle between two meteors at \(t-1\) and \(t\) (in degree). This is a classification criterion.
3.1.27. --trk-star-min
- Deprecated
--fra-star-min
- Type
INTEGER
- Default
15
- Example
--trk-star-min 5
Minimum number of frames required to track a star. This is a classification criterion.
3.1.28. --trk-meteor-min
- Deprecated
--fra-meteor-min
- Type
INTEGER
- Default
3
- Example
--trk-meteor-min 5
Minimum number of frames required to track a meteor. This is a classification criterion.
3.1.29. --trk-meteor-max
- Deprecated
--fra-meteor-max
- Type
INTEGER
- Default
100
- Example
--trk-meteor-max 50
Maximum number of frames required to track a meteor. This is a classification criterion.
3.1.30. --trk-ddev
- Deprecated
--diff-dev
- Type
FLOAT
- Default
4.0
- Example
--trk-ddev 5.5
Multiplication factor of the standard deviation (CC error has to be higher than \(ddev \times stddev\) to be considered in movement). This is a classification criterion.
3.1.31. --trk-ell-min
- Type
FLOAT
- Default
0.0
- Example
--cca-ell --trk-ell-min 3.0
Minimum ellipse ratio to be considered as a meteor. This is a classification
criterion. If the value is 0
then this parameter has no effect. Moreover,
this parameter requires the --cca-ell parameter to work. If the
latest is not set, then this parameter is ignored.
3.1.32. --trk-all
- Deprecated
--track-all
- Type
BOOLEAN
- Example
--trk-all
By default the program only tracks meteor
object type. If --trk-all
is
set, all object types are tracked (meteor
, star
or noise
).
This parameter is used in the _tracking_perform()
function.
3.1.33. --trk-roi-path
- Type
STRING
- Default
[empty]
- Example
--trk-roi-path trk2roi.txt
Path to the output file containing lists of the RoI ids of the tracked objects. Each line corresponds to a track/object and here is the corresponding line format:
{tid} {otype} {rid1} {rid2} {...} {ridn}
{rid1}
is the first RoI id of the track/object of {tid}
id.
{rid2}
is the second RoI id (in the second frame where the object
has been tracked). And so on, until the last RoI id {ridn}
. Note
that sometime the RoI id can be 0
, it means that the object has been
extrapolated on this frame, thus there is no RoI id for this frame.
3.1.34. --log-path
- Deprecated
--out-stats
- Type
STRING
- Default
[empty]
- Example
--log-path detect_logs/
Path of the output statistics, only required for debugging purpose.
Warning
This section targets advanced users, some knowledge about the implemented algorithms may be required!! You have been warned ;-).
fmdt-detect
comes with the --log-path
option to help to understand what
is happening during the execution. This option enables to log internal
statistics of the different algorithms used to detect meteors.
The folder contains multiple files, one per frame. For instance, the file name
for the frame n°12 is: 00012.txt
. Each file contains 5 different tables:
Table 1: list of RoIs at \(t - 1\) (result of the CCL/CCA + hysteresis algorithm at \(t - 1\)),
Table 2: list of RoIs at \(t\) (result of the CCL/CCA + hysteresis algorithm at \(t\)),
Table 3: list of associations between \(t - 1\) RoIs and \(t\) RoIs (result of the k-NN algorithm) + errors/velocities after motion estimation,
Table 4: motion estimation statistics between \(t - 1\) and \(t\) frame,
Table 5: list of tracks since the beginning of the execution (final output of the detection chain).
Note
The first log file (usally named 00000.txt
) only contains the
table 2. This is normal because algorithms starting from k-NN require two
consecutive frames to work.
3.1.34.1. Table 1 and table 2: RoIs
# ------||----------------||---------------------------||-------------------------------------------||-------------||-----------||------------||-------------------
# RoI || Track || Bounding Box || Surface (S in pixels) || Center || Magnitude || Saturation || Ellipse
# ------||----------------||---------------------------||-------------------------------------------||-------------||-----------||------------||-------------------
# ------||------|---------||------|------|------|------||-----|------|------|-------|-------|-------||------|------||-----------||------------||-----|-----|-------
# ID || ID | Type || xmin | xmax | ymin | ymax || S | Sx | Sy | Sx2 | Sy2 | Sxy || x | y || -- || Counter || a | b | ratio
# ------||------|---------||------|------|------|------||-----|------|------|-------|-------|-------||------|------||-----------||------------||-----|-----|-------
{rid} || {tid}| {otype} ||{xmin}|{xmax}|{ymin}|{ymax}|| {S} | {Sx} | {Sy} | {Sx2} | {Sy2} | {Sxy} || {cx} | {cy} || {mag} || {sat} || {a} | {b} | {r}
Each line corresponds to one RoI:
{rid}
: unique identifier for the current RoI (start from 1),{tid}
: unique identifier of the corresponding track (start from 1), can be, empty if no track is associated to the current RoI,{otype}
: type of the track object (meteor
,noise
orstar
), only if there is a track corresponding to this RoI,{xmin}
: minimum \(x\) position of the bounding box,{xmax}
: maximum \(x\) position of the bounding box,{ymin}
: minimum \(y\) position of the bounding box,{ymax}
: maximum \(y\) position of the bounding box,{S}
: surface (area) of the RoI in pixels,{Sx}
: sum of \(x\) properties,{Sy}
: sum of \(y\) properties,{Sx2}
: sum of \(x^2\) properties,{Sy2}
: sum of \(y^2\) properties,{Sxy}
: sum of \(x \times y\) properties,{cx}
: \(x\) center of mass,{cy}
: \(y\) center of mass,{mag}
: magnitude of the current RoI (accumulated brightness of the RoI),{sat}
: number of pixels that are saturated in the current RoI (a pixel \(x\) is saturated when its intensity \(i_x = 255\)),{a}
: semi-major axis (ellipse),{b}
: semi-minor axis (ellipse),{r}
: ratio \(a / b\).
{mag}
and {sat}
features are not enabled by default (and the -
character is printed in the corresponding columns). To enable theses features
you need to use the --cca-mag command line parameter. For more
information about those features you can refer to the
_features_compute_magnitude()
function.
{a}
, {b}
and {r}
features are are not enabled by default (and the
-
character is printed in the corresponding columns). To enable theses
features you need to use the --cca-ell command line parameter. For
more information about those features you can refer to the
_features_compute_ellipse()
function.
3.1.34.2. Table 3: List of associations between RoIs
# --------------------||---------------||------------------------||-----------
# RoI ID || Distance || Error (or velocity) || Motion
# --------------------||---------------||------------------------||-----------
# ----------|---------||--------|------||-------|-------|--------||-----------
# t-1 | t || pixels | rank || dx | dy | e || is moving
# ----------|---------||--------|------||-------|-------|--------||-----------
{rid_t-1} | {rid_t} || {dist} | {k} || {dx} | {dy} | {e} || {mov}
Each line corresponds to an association between one RoI at \(t - 1\) and at \(t\):
{rid_t-1}
: id of the RoI in the table 1 (in the \(t - 1\) frame),{rid_t}
: id of the RoI in the table 2 (in the \(t\) frame),{dist}
: distance in pixels between the two RoIs,{rank}
: rank in the k-NN algorithm, if 1: it means that this is the closest RoI association, if 2: it means that this is the second closest RoI association, etc.,{dx}
: \(x\) distance between the estimated position (after motion estimation) and the real position (in frame \(t - 1\)),{dy}
: \(y\) distance between the estimated position (after motion estimation) and the real position (in frame \(t - 1\)),{e}
: euclidean distance between the estimated position and the real position,{mov}
:yes
if the RoI is moving,no
otherwise. The criteria to detect the motion of an RoI is: \(|e - \bar{e^1_t}| > \sigma^1_t\), with \(e\) the error of the current RoI, \(\bar{e^1_t}\) the mean error after the first motion estimation and \(\sigma^1_t\) the standard deviation after the first motion estimation.
If {mov}
= yes
then, {dx}
, {dy}
is the velocity vector and
{e}
is the velocity norm in pixel.
Note
{dx}
, {dy}
, {e}
and {mov}
are computed after the
second motion estimation.
3.1.34.3. Table 4: Motion Estimation Statistics
# ------------------------------------------------------||------------------------------------------------------
# First motion estimation (with all associated RoIs) || Second motion estimation (exclude moving RoIs)
# ------------------------------------------------------||------------------------------------------------------
# ----------|----------|----------|----------|----------||----------|----------|----------|----------|----------
# theta | tx | ty | mean err | std dev || theta | tx | ty | mean err | std dev
# ----------|----------|----------|----------|----------||----------|----------|----------|----------|----------
{theta1} | {tx1} | {ty1} |{mean_er1}|{std_dev1}|| {theta2} | {tx2} | {ty2} |{mean_er2}|{std_dev2}
There is only one line in this table. It represents the motion estimation between frame \(t - 1\) and frame \(t\):
{theta}
: the estimated rotation angle between frame \(t\) and frame \(t - 1\),{tx}
and{ty}
: the estimated translation vector from frame \(t\) to frame \(t - 1\),{mean_er}
: the mean error of the associated RoIs,{std_dev}
: the standard deviation of the associated RoI errors.
The first estimation considers all the associated RoIs while the second estimation excludes the associated RoIs in movement. To be considered in movement, an RoI has to verify the following condition: \(|e - \bar{e^1_t}| > \sigma^1_t\), with \(e\) the error of the current RoI, \(\bar{e^1_t}\) the mean error after the first motion estimation and \(\sigma^1_t\) the standard deviation after the first motion estimation.
3.1.34.4. Table 5: List of Tracks
# -----------------||---------------------------||---------------------------||---------||-------------------
# Track || Begin || End || Object || Reason of changed
# -----------------||---------------------------||---------------------------||---------|| state (from
# -------|---------||---------|--------|--------||---------|--------|--------||---------|| meteor to noise
# Id | State || Frame # | x | y || Frame # | x | y || Type || object only)
# -------|---------||---------|--------|--------||---------|--------|--------||---------||-------------------
{tid} | {state} || {fbeg} | {xbeg} | {ybeg} || {fend} | {xend} | {yend} || {otype} || {reason}
Most of the columns of this table have been described in the Standard Output section, here we focus only on extra columns:
{state}
: current state of the track (in a finite state machine): can beupdated
,lost
orfinished
. First, when a track is created, its state isupdated
. Then,updated
can becomelost
.lost
can become eitherfinished
orupdated
.finished
is a final state.{reason}
: reason of the classification frommeteor
tonoise
.
3.1.35. --vid-out-path
- Type
STRING
- Default
[empty]
- Example
--vid-out-path ~/Videos/out_video.mp4
Output video path with the bounding boxes around the detected tracks (supports
also a path to a sequence of images path/basename_%05d.jpg
).
3.1.36. --vid-out-play
- Type
BOOLEAN
- Example
--vid-out-play
Open an SDL window to show the output video of the detected tracks (shows the bounding boxes around the detected tracks)
3.1.37. --vid-out-id
- Type
BOOLEAN
- Example
--vid-out-id
Work only if --vid-out-path or --vid-out-play is set.
Display the track ids corresponding to the bounding boxes. Requires to link with
OpenCV library (-DFMDT_OPENCV_LINK
CMake option,
see Section 2.2.1).