Skip to content

Latest commit

 

History

History
169 lines (106 loc) · 10.1 KB

tool-usage.md

File metadata and controls

169 lines (106 loc) · 10.1 KB

Tools Usage

Several tools are provided with MetDetPy to support related functions.

Menu

Toolkit

Data Format

ClipToolkit

ClipToolkit can be used to create multiple video segments from a single video or a stack of images from these video segments at once. Starting from MetDetPy v2.2.0, ClipToolkit has expanded its invocation methods to support more flexible usage and more general scenarios.

Its usage is as follows:

python ClipToolkit.py target [json] [--start-time START_TIME] [--end-time END_TIME]
                      [--mode {image,video}] [--suffix SUFFIX]
                      [--save-path SAVE_PATH] [--resize RESIZE]
                      [--png-compressing PNG_COMPRESSING]
                      [--debayer] [--debayer-pattern DEBAYER_PATTERN]
                      [--jpg-quality JPG_QUALITY] [--debug]

Usage Explanation

ClipToolkit can accept three input modes, which are primarily determined by the positional arguments passed in. These modes and the corresponding usage of positional arguments are as follows:

  1. Ordinary Mode The ordinary mode is the basic mode starting from v1.3.0, which can be used to create multiple stacked images or video clips at once, and can configure the name and path for each image/video. To run ClipToolkit in ordinary mode, two positional arguments need to be passed in: target (the path to the target video file) and json (a JSON-formatted string or the path to a JSON file). In this context, the json should be a JSON array containing several sets of start time, end time, and optionally filename information. Each element should include:

    • A required "time" key, the value of which should be an array consisting of two strings in the "hh:mm:ss.ms" format, representing the start and end times of the segment.
    • An optional "filename" key, where you can specify the filename and extension in its value (indicating the format to which the video clip should be converted and named).

    In this mode, the filename and type options specified in the JSON will be prioritized. Optional parameters will only take effect when there are no corresponding parameters. An example of a JSON instance is clip_test.json. Usage is as follows:

python ClipToolkit.py ./test/20220413Red.mp4 ./test/clip_test.json --mode image --suffix jpg --jpg-quality 60 --resize 960x540 --save-path ./test
  1. Simplified Mode The simplified mode is enabled by passing only a video file as a positional argument, used to generate a single image stack or video clip. The start and end times, format, and other parameters for the generated file need to be specified through optional parameters, defaulting to a single JPG format image stack of the entire video. In this mode, there is no need to construct a JSON file or escape strings, making it easier to use. Its usage is as follows:
python ClipToolkit.py ./test/20220413Red.mp4 --start-time 00:03:00 --end-time 00:05:00 --mode image --output-name 。/test/generated_img.jpg
  1. Sample Generating Mode Sample Generating Mode suits for condition when you want to generate all stacked images or video clips for detection results (or annotations). This mode can be enabled by specifying only a JSON file in MDRF format as input (an introduction to this file format can be found at Meteor Detection Recording Format (MDRF)). This format file can be generated by evaluate or MetDetPy since MetDetPy v2.2.0. Remaining parameters are specified through optional parameters. This can be used to generate a batch of annotated images for fine-tuning models. Its usage is as follows:
python ClipToolkit.py ./test/video_mdrf.json --mode video

Optional Parameters

Supported optional parameters in ClipToolkit are as follows：

  • --start-time: The start time of the segment. It can be specified using milliseconds or in the HH:MM:SS.ms format. This is only effective in simplified mode. The default is the start time of the video.

  • --end-time: The end time of the segment. It can be specified using milliseconds or in the HH:MM:SS.ms format. This is only effective in simplified mode. The default is the end time of the video.

  • --mode: Convert the clip to an image or video. It should be selected from {image, video}. This option will be overridden by specific filenames in the JSON.

  • --suffix: the suffix of the output. By default, it is "jpg" for image mode and "avi" for video mode. This option will be covered by a specific filename in JSON.

  • --save-path: the path where image(s)/video(s) are placed. When only one clip is provided in JSON, you can include the filename in --save-path to simplify your JSON.

  • --resize: resize image/video to the given resolution. It should be a string where two numbers are joined by x,like 960x540 or 1920x1080.

  • --png-compressing: the compressing rate of the generated png image. It should be int ranged $Z \in [0,9]$; By default, it is 3.

  • --jpg-quality: the quality of generated jpg image. It should be int ranged $Z \in [0,100]$; By default, it is 95.

  • --debug: run in debug mode to print more detailed information.

Notice: if using a JSON-format string instead of the path to a JSON file, you should be really careful about the escape of double quotes in command lines.

Evaulate

Evaluate is an integrated performance evaluation and effect testing tool. It can be used to generate result reports, evaluate the utilization of device resources, and compare differences between results.

To evaluate how MetDetPy performs on your video, you can simply run evaluate.py :

python evaluate.py target [--cfg CFG] [--load LOAD] [--save SAVE] [--metrics] [--debug] video_json

Arguments

  • json: A JSON file in MDRF format, which needs to contain the necessary information related to the video (video file and mask file paths, start and end times) to initiate. Its format should meet the requirements specified in Meteor Detection Recording Format (MDRF).

  • --cfg: Configuration file. By default, it uses the default configuration, which is m3det_normal.json.

  • --load: Compared target result. If this is enabled with a path to another JSON, evaluate.py will directly load its results for comparison as the current detection result instead of running detection through the video.

  • --save: The path and filename where the detection results will be saved.

  • --metrics: Depending on the category of the provided JSON file, it performs regression testing (comparing with other prediction results) or calculates detection precision and recall (comparing with ground truth). To apply this option, the json file needs to contain results information.

  • --debug: When starting evaluate.py with this option, detailed debug information will be provided.

Example

(To be updated)

Package python codes to executables

We provide make_package.py to freeze MetDetPy programs into stand-alone executables. This tool supports to use pyinstaller or nuitka to package/compile MetDetPy (and related tools).

When using it, make sure that either pyinstaller or nuitka is installed. Besides, when using nuitka as the packaging tool, make sure that at least one C/C++ compiler is available on your computer.

Its usage is as follows:

python make_package.py [--tool {nuitka,pyinstaller}] [--mingw64]
     [--apply-upx] [--apply-zip] [--version VERSION]

  • --tool: your compile/package tool. It should be selected from {nuitka,pyinstaller}. nuitka is the default option.

  • --mingw64: use the mingw64 compiler. Only worked when using nuitka and your OS is windows.

  • --apply-upx: apply UPX to squeeze the size of the executable program. Only worked when using nuitka.

  • --apply-zip: generate zip package when compiling/packaging is finished.

  • --version: MetDetPy version tag. Used for naming zip package.

The target executable file and its zip package version (if applied) will be generated in dist directory.

Notice:

  1. It is suggested to use Python>=3.9, pyinstaller>=5.0, and nuitka>=1.3.0 to avoid compatibility issues. You can prepare either tool to package the program.
  2. Due to the feature of Python, neither tools above can generate cross-platform executable files.
  3. If matplotlib or scipy is in the environment, they are likely to be packaged into the final directory together. To avoid this, it is suggested to use a clean environment when packaging.

Meteor Detection Recording Format (MDRF)

Starting with Version 2.2.0, MetDetPy formally introduces the Meteor Detection Recording Format (MDRF) as the standard format for the MetDetPy toolkit. MDRF files are JSON-format text files containing specific key-value pairs that store essential information about meteor detection results, performances or annotations. These files can be generated either through detection or manual annotation as ground truth, and can serve as both input and output across most MetDetPy toolkit components.

Essential key-values of MDRF

A valid MDRF file requires the following keys with values:

{
    "version":"VERSION",
    "basic_info":{...},
    "type":"prediction",
    "anno_size":[int,int],
    "results":list[results]
}

in which: Among them:

  • "version": The value represents the current version of MetDetPy.
  • "basic_info": Contains the basic information of the video, including fields such as "mask", "start_time", "end_time", and "runtime_resolution", which are used to correctly construct video segments.
  • "type": Indicates the nature of the MDRF (whether it belongs to the ground truth "ground-truth" or is a prediction by MetDetPy "prediction").
  • "anno_size": Indicates the resolution of the annotation or prediction.
  • "results": A list of results.