.. include:: names.rst .. toctree:: :maxdepth: 2 Basic Command-line Usage ======================== |trex| is usually launched from the command-line (with or without parameters), which will show a file opening dialog by default. You probably *should* get familiar with the graphical user-interface of |trex| as well - for example, it makes it easy to detect trouble with parameter values immediately and gives you feedback after changing tracking parameters that you wouldn't get on the command-line. To see how that works, and for some additional detail on the general principles, have a look at :doc:`tutorials`. The following sections, however, address directly providing parameters using the command-line (e.g. in a batch processing, or generally a more command-line affine use-case). Any additional number of parameters can be passed to |trex| as:: trex [...] -PARAMETER VALUE For example, in order to set the number of individuals to 5 and prefix all individuals names/files with "termite" instead of "fish", just change the values of ``track_max_individuals`` and ``individual_prefix`` when launching the application like so (we are also opening a file called "example.mp4" and use a specific settings file):: trex -i example.mp4 -s tmp.settings -track_max_individuals 5 -individual_prefix "termite" If you've never run the program before on that specific video file, it'll first convert the mp4 file to a pv file and save an ``example.settings`` file. Conversion might take a bit - especially if its a particularly long video. Next time, however, it will open any existing pv files in tracking mode directly - if you want to generate the pv file again, you'd have to add force the task to ``convert`` like this:: trex -i example.mp4 [...] -task convert This will overwrite an existing ``example.pv`` (and ``example.settings``) file in that same folder. Most parameters (except system-variables) can be adjusted after loading a video. A full reference of them is at :doc:`parameters_trex`. .. NOTE:: There is the possibility of starting it directly using a desktop short-cut (or double-clicking the executable itself), but this requires either a manual compile or changes to your environment variables (see :ref:`run-by-clicking`) which are not officially supported at the moment. Basic principles & Good practices --------------------------------- |trex| offers many parameters that can be set by users. However, that does not mean that all parameters have to be considered in all cases. In fact, most of them will already be set to reasonable values that work in many situations: *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 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``. Command-line parameters always override settings files. If you know the number of individuals, specify before you do the tracking (using the parameter :param:`track_max_individuals`). When converting videos, :param:`cm_per_pixel` should always be set to provide a valid conversion factor between pixels and real-world coordinates. By default, it's set to ``1`` - meaning there's no conversion and all units (even if it says they are ``cm``) are in pixels. You can set ``cm_per_pixel`` within the |trex| GUI, either in the initial settings dialog (under "tracking" > "calibrate") or in the tracking view. There, simply CTRL/⌘ + click into an empty spot of the arena. Hold CTRL/⌘ and click somewhere else: a button will pop up to define the selected length as a specific real-world length. See here: `changing the cm to px conversion factor `_. Using settings files -------------------- The format is:: parameter_name = value parameter2 = value2 If you save this as ``videoname.settings`` in your output directory (e.g. by default the same folder as your input video), |trex| will load these settings before loading any command-line parameters. Command-line, however, always overwrites anything loaded from ``.settings`` files. .. _parameter-order: Setting parameters in the correct order --------------------------------------- Preferably set parameters in this order (with the goal to only match those objects that are your objects of interest, and exclude the ones that you do not want to track): - :param:`cm_per_pixel` (in .settings files, command-line or in |trex|) - :param:`track_threshold` - :param:`track_size_filter` Now all objects of interest should have a cyan number next to them in RAW view (pressing ``D`` in tracking view switches to RAW and vice-versa). More "optional" parameters like can now be set in order to maximize the length of tracklets: - :param:`track_max_speed` - :param:`track_max_reassign_time` - :param:`track_posture_threshold` - :param:`outline_resample` - :param:`outline_curvature_range_ratio` Other command-line 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:: $ pvinfo -i