Skip to content

usage.md

Latest commit

 

History

History
240 lines (172 loc) · 9.23 KB

usage.md

File metadata and controls

240 lines (172 loc) · 9.23 KB

API Documentation

This class provides functionalities for:

  • training/evaluating/repairing YOLOv7 models,
  • object detection using YOLOv7 models,
  • numerical analysis on TensorFlow neural networks.

Usage

Instantiate an object of the Class Name class to access the provided methods.

Example:

dnnTest = DNNTest()
dnnTest.detect_yolov7("./path/to/images.jpg", "./path/to/yolov7/weights.pt")

Method: prepare_dataset

This method prepares a dataset for training a YOLOv7-like model by organizing the image and label data into the required directory structure.

Parameters

  • dataset_name (optional, default: ""): Name of the dataset. This name will be used to create a directory for the prepared dataset.
  • image_path (optional, default: ""): Path to the directory containing the source images. If the path does not start with "/root", it will be appended to the "/root" directory.
  • label_path (optional, default: ""): Path to the directory containing the source labels. If the path does not start with "/root", it will be appended to the "/root" directory.
  • train_val_ratio (optional, default: 0.8): Ratio of training to validation data. This parameter determines how the dataset will be split into training and validation sets.

Returns

  • res_path: Path to the prepared dataset directory.

Example Usage

from api import DNNTest
dnnTest = DNNTest()
# Prepare a dataset named "my_dataset" with default parameters
result = dnnTest.prepare_dataset(dataset_name="demo", image_path="/path/to/images", label_path="/path/to/labels")

Method: train_yolov7

The train_yolov7 method trains a YOLOv7 model using the specified parameters.

Parameters

  • proj_name (str, optional): The name of the project. Default is "pilotstudy".
  • data_path (str, optional): The path to the data YAML file. Default is "/root/MetaHand/tools/yolov7/pilotstudy/data.yaml".
  • img_size (int, optional): The size of the input images. Default is 640.
  • batch_size (int, optional): The batch size for training. Default is 42.
  • num_workers (int, optional): The number of parallel workers for data loading. Default is 4.
  • num_epoch (int, optional): The number of training epochs. Default is 300.
  • cfg_path (str, optional): The path to the configuration file. Default is "cfg/training/yolov7.yaml".

Raises

  • ValueError: If the specified data_path does not exist.

Example Usage

from api import DNNTest
dnnTest = DNNTest()
result = dnnTest.train_yolov7(proj_name="demo_proj", data_path="/root/MetaHand/tools/yolov7/demo/data.yaml")

Method: detect_yolov7

Performs object detection using the YOLOv7 model.

Parameters

  • img_path (str): The path to the input image file. Only JPEG images are supported.
  • weights_path (str): The path to the YOLOv7 model weights file.
  • size (int, optional): The input image size for detection. Defaults to 320.
  • confidence (float, optional): The confidence threshold for detected objects. Defaults to 0.25.

Returns

  • res_path (str): The path to the output image file with detected objects. The file will be saved in the following format: ./MetaHand/tools/yolov7/runs/detect/{model_name}/{img_name}/{img_name}.

Example Usage

from api import DNNTest
dnnTest = DNNTest()
img_path = "/path/to/input/image.jpg"
weights_path = "/path/to/model/weights.pt"
output_path = dnnTest.detect_yolov7(img_path, weights_path)
print("Detection result saved at:", output_path)

Method: detect_yolov7_dir

The detect_yolov7_dir method is used to perform object detection using the YOLOv7 model on a directory of images.

Parameters

  • img_path (str, optional): The path to the directory containing the images to be processed. Default value is "/root/MetaHand/tools/yolov7/pilotstudy/images/train".
  • weights_path (str, optional): The path to the weights file of the YOLOv7 model. Default value is "/root/MetaHand/tools/yolov7/runs/train/pilotstudy_640/weights/best.pt".
  • size (int, optional): The size of the input images for the YOLOv7 model. Default value is 640.
  • confidence (float, optional): The confidence threshold for object detection. Default value is 0.25.

Returns

  • res_path (str): The path to the result file generated by the object detection process.

Example Usage

from api import DNNTest
dnnTest = DNNTest()
img_dir = "/path/to/images/dir"
weights_path = "/path/to/model/weights.pt"
output_path = dnnTest.detect_yolov7_dir(img_dir, weights_path)
print("Detection result saved at:", output_path)

Method: mutate_image

Generate mutated images on target image_path. If the image_path is a directory, this function will mutate all images inside the directory. If the image_path is a file, this function will mutate the target image.

Parameters

  • file_or_directory (str): "file" or "directory"
  • image_path (str): Path to the image file or directory.
  • label_path (str): Path to the label file.
  • output_path (str, optional): Directory that stores mutated images. Defaults to "./MetaHand/data_pilot_test/test_mutate".
  • mutate_type (str, optional): Type of mutation. "background" or "object". Defaults to "object".
  • mutate_ratio (str, optional): Mutation ratio in the range of 0.0-1.0. Defaults to "0.9".
  • noise_intensity (str, optional): Noise intensity in the range of 0.0-1.0. Defaults to "16.0".
  • label_format (str, optional): Label format. "darknet" or "coco". Defaults to "darknet".

Returns

  • str: The directory of mutated images.

Example Usage

from api import DNNTest

# Create an instance of YourClass
dnnTest = DNNTest()

# Call the mutate_image method
output_directory = dnnTest.mutate_image(file_or_directory="file",
                                            image_path="/path/to/image.jpg",
                                            label_path="/path/to/label.txt",
                                            output_path="./output",
                                            mutate_type="object",
                                            mutate_ratio="0.9",
                                            noise_intensity="16.0",
                                            label_format="darknet")

Method: evaluate_yolov7

This method is used to evaluate the YOLOv7 model with customized parameters.

Parameters

  • data_dir (str, optional): The directory path containing the data for evaluation. Default value is "/root/MetaHand/tools/yolov7/pilotstudy".
  • weights_path (str, optional): The path to the weights file of the YOLOv7 model. Default value is "/root/MetaHand/tools/yolov7/runs/train/pilotstudy_640/weights/best.pt".
  • mutate_type (str, optional): The type of mutation to apply. Default value is "ObjectGaussianMutation".
  • mutate_ratio (str, optional): The mutation ratio. Default value is "03".
  • mutate_strength (int, optional): The strength of the mutation. Default value is 160.
  • threshold (float, optional): The detection threshold. Default value is 0.3.
  • jobs (int, optional): The number of jobs to run in parallel. Default value is 8.

Returns

  • violation_path (str): The path to the file containing the detected violations.

Example Usage

from api import DNNTest
dnnTest = DNNTest()
violation_path = dnnTest.evaluate_yolov7(
    data_dir="/root/MetaHand/tools/yolov7/pilotstudy",
    weights_path="/custom/weights/path",
    mutate_type="ObjectGaussianMutation",
    mutate_ratio="03",
    mutate_strength=160,
    threshold=0.3,
    jobs=4
)
print(f"The list of violated inference are stored in {violation_path}")

Method: repair_yolov7

This method repairs a YOLOv7 model by generating new training data based on the detected violations in the existing model. It performs the following steps:

  1. Evaluates the YOLOv7 model using the specified parameters.
  2. Moves the violation file to a new directory.
  3. Prepares the new training data based on the violations.
  4. Updates the YAML configuration file with the new training data.
  5. Trains the YOLOv7 model with the new data.

Parameters

  • data_dir (string, optional): The directory path where the YOLOv7 data is located. Default is "/root/MetaHand/tools/yolov7/pilotstudy".
  • weights_path (string, optional): The path to the weights file of the YOLOv7 model. Default is "/root/MetaHand/tools/yolov7/runs/train/pilotstudy_640/weights/best.pt".
  • mutate_type (string, optional): The type of mutation used for generating new training data. Default is "ObjectGaussianMutation".
  • mutate_ratio (string, optional): The ratio used for the mutation. Default is "03".
  • mutate_strength (int, optional): The strength parameter for the mutation. Default is 160.
  • threshold (float, optional): The threshold value for the YOLOv7 evaluation. Default is 0.3.
  • img_size (int, optional): The size of the input images for training. Default is 640.
  • num_epoch (int, optional): The number of epochs to train the repaired YOLOv7 model. Default is 300.

Returns None

Example Usage

from api import DNNTest
dnnTest = DNNTest()
dnnTest.repair_yolov7(
    data_dir="/root/MetaHand/tools/yolov7/pilotstudy",
    weights_path="/custom/weights/path",
    mutate_type="ObjectGaussianMutation",
    mutate_ratio="03",
    mutate_strength=160,
    img_size=640,
    num_epoch=10,
    jobs=4
)