{ "cells": [ { "cell_type": "markdown", "id": "5eceb175", "metadata": {}, "source": [ "# Using the command line interface\n", "Tintx also comes with a simple command line interface (cli) to apply tracking and visualise tracking data.\n", "After installing `tintx` you will have `tintx` available to your command line. Like with most command line tools you can inspect the help menu using the `--help` flag:" ] }, { "cell_type": "code", "execution_count": 1, "id": "1cb8db90", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Usage: tintx [OPTIONS] COMMAND [ARGS]...\n", "\n", " Command line interface (cli) of the tintX tracking algorithm.\n", "\n", " The cli offers two sub commands. One for applying the tracking algorithm,\n", " one for visualisation of already tracked data.\n", "\n", "Options:\n", " -V, --version Show the version and exit.\n", " -h, --help Show this message and exit.\n", "\n", "Commands:\n", " plot Plot/Animate existing tracking data.\n", " track Apply the tintX tracking algorithm.\n" ] } ], "source": [ "tintx --help" ] }, { "cell_type": "markdown", "id": "d458bdbd", "metadata": {}, "source": [ "As the help menu suggests the `tintx` command comes with two sub commands (`track` and `plot`)." ] }, { "cell_type": "markdown", "id": "f3ec09a1", "metadata": {}, "source": [ "## Applying the tracking algorithm\n", "The `track` sub command can be used to apply tracking:" ] }, { "cell_type": "code", "execution_count": 2, "id": "5b59dafd", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Usage: tintx track [OPTIONS] VARIABLE [INPUT_FILES]...\n", "\n", " Apply the tintX tracking algorithm.\n", "\n", " The sub command takes at least two arguments and attempts of read data saved\n", " in netcdf/grib format and apply the tracking to a data variable within the\n", " dataset.\n", "\n", " Arguments:\n", "\n", " variable: Variable name of the data that is tracked\n", "\n", " input_files: Filename(s) or Directory where the data is stored.\n", "\n", "Options:\n", " -s, --start TEXT ISO-8601 string representation of the first tracking\n", " time step.\n", " -e, --end TEXT ISO-8601 string representation of the last tracking\n", " time step.\n", " --x-coord TEXT Name of the X (eastward) coordinate\n", " --y-coord TEXT Name of the Y (northward) coordinate\n", " --time-coord TEXT Name of the time coordinate\n", " -o, --output PATH Output file where the tracking results pandas\n", " DataFrame is saved to. If `None` given (default) the\n", " output filename will be set from the input meta data\n", " and the variable name.\n", " --field-thresh FLOAT Threshold used for object detection. Detected\n", " objects are connected pixels above this threshold.\n", " --iso-thresh FLOAT Used in isolated cell classification. Isolated cells\n", " must not be connected to any other cell by\n", " contiguous pixels above this threshold.\n", " --min-size FLOAT Minimum size threshold in pixels for an object to be\n", " detected.\n", " --search-margin FLOAT Radius of the search box around the predicted object\n", " center.\n", " --flow-margin FLOAT Margin size around objects to perform phase\n", " correlation.\n", " --max-disparity FLOAT Maximum allowable disparity value.\n", " --max-flow-mag FLOAT Maximum allowable global shift magnitude.\n", " --max-shift-disp FLOAT Maximum magnitude of difference in meters per second\n", " for two shifts to be considered in agreement.\n", " --gs-alt FLOAT Altitude in meters at which to perform phase\n", " correlation for globalshift calculation. 3D data\n", " only\n", " --iso-smooth FLOAT Gaussian smoothing parameter in peak detection\n", " preprocessing.\n", " -h, --help Show this message and exit.\n" ] } ], "source": [ "tintx track --help" ] }, { "cell_type": "markdown", "id": "04f15e19", "metadata": {}, "source": [ "We can for example apply the tracking to the radar estimates. The radar estimates are saved in netCDF files with the longitude variable saved as `longitude` and the latitude variable saved as `latitude`. The variable name is `radar_estimated_rain_rates`. Let's apply the tracking and save the tracks to a hdf5 file." ] }, { "cell_type": "code", "execution_count": 11, "id": "ed9e2915", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Tracking: 49it [00:01, 25.53it/s] \n", "Found and tracked 125 objects.\n" ] } ], "source": [ "tintx track radar_estimated_rain_rate $DATA_FILES/CPOL_radar.nc \\\n", " --field-thresh 0.1 --min-size 4 --x-coord longitude --y-coord latitude \\\n", " -s 2006-11-16T03:00 -e 2006-11-16T11:00 -o /tmp/output.h5" ] }, { "cell_type": "markdown", "id": "2d778122", "metadata": {}, "source": [ "## Plotting the data\n", "The `plot` sub command can be used to plot data that has as already been tracked:" ] }, { "cell_type": "code", "execution_count": 4, "id": "ae6eb5d5", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Usage: tintx plot [OPTIONS] INPUT_FILE\n", "\n", " Plot/Animate existing tracking data.\n", "\n", " Arguments:\n", "\n", " input_files: Filename of the HDF5 file containing the tracking data.\n", "\n", "Options:\n", " -o, --output FILE Path to a visualisation of the tracking. If `None`\n", " is given, no visualisation will be created. The\n", " type of visualisation will be determined from the\n", " file type. E.i for `.png` or `.jpg` files\n", " trajectory plots will be created for `.mp4`, `.gif`\n", " animations will be created.\n", " --animate Create animation\n", " --dt FLOAT Offset in hours from UTC. Animation only\n", " --fps FLOAT Play back speed of an animation. Animation only\n", " --cmap TEXT Colormap used for animations.\n", " --vmin FLOAT minimum values to be plotted\n", " --vmax FLOAT Maximum values to display. Animation only\n", " --mintrace FLOAT Minimum length of a trace to be plotted: Trajectory\n", " plot only\n", " -ms, --markersize FLOAT Help marker size of the trijectory plot\n", " -lw, --linewidth FLOAT Line width to be plotted.\n", " -h, --help Show this message and exit.\n" ] } ], "source": [ "tintx plot --help" ] }, { "cell_type": "markdown", "id": "b2c69dd0", "metadata": {}, "source": [ "Let's create a plot of the tracks that have been identified. " ] }, { "cell_type": "code", "execution_count": 7, "id": "2fb2f0df", "metadata": {}, "outputs": [], "source": [ "tintx plot /tmp/output.h5 -o tracks_new.png -lw 1 -ms 35" ] }, { "cell_type": "markdown", "id": "1e4d4f85", "metadata": {}, "source": [ "This will result in the following image:\n", "![Resulting track image](tracks_new.png)" ] } ], "metadata": { "kernelspec": { "display_name": "Bash", "language": "bash", "name": "bash" }, "language_info": { "codemirror_mode": "shell", "file_extension": ".sh", "mimetype": "text/x-sh", "name": "bash" } }, "nbformat": 4, "nbformat_minor": 5 }