CrowdDet Documentation

To run CrowdDet, it is recommended to use Docker. You must have nvidia-docker installed on your host machine.

1. Build the Docker image:

sudo docker build . -t crowddet

2. Run the Docker container: Use the --gpus all flag to enable GPU support and --shm-size=8g to ensure sufficient shared memory for training.

sudo docker run --gpus all --shm-size=8g -it --rm crowddet

After testing, you can perform evaluation, single-image inference, or visualization using the following scripts in the tools directory:

1. Evaluate a JSON result file:

   • -f: Path to the JSON file.

   python3 eval_json.py -f your_json_path.json

2. Run inference on a single image:

   • -md: Model name.
   • -r: Resume epoch.
   • -i: Path to the input image.

   python3 inference.py -md rcnn_fpn_baseline -r 40 -i your_image_path.png

3. Visualize results from a JSON file:

   • -f: Path to the JSON file.
   • -n: Number of visualization pictures to generate.

   python3 visulize_json.py -f your_json_path.json -n 3

cd tools
python3 eval_json.py -f your_json_path.json
python3 inference.py -md rcnn_fpn_baseline -r 40 -i your_image_path.png 
python3 visulize_json.py -f your_json_path.json -n 3

Testing is performed using the test.py script in the tools directory.

• -md: The model name to use.
• -r: The epoch to resume from.
• -d: GPU IDs to use (e.g., -d 0-3 to use four GPUs).

The resulting JSON file is evaluated automatically.

cd tools
python3 test.py -md rcnn_fpn_baseline -r 40

Training is performed using the train.py script located in the tools directory. You can specify the model name using the -md flag. Additional training and testing configurations are managed in config.py.

cd tools
python3 train.py -md rcnn_fpn_baseline

The eval_MR() method calculates the log-average miss rate (MR) using Caltech-style anchor points. This is useful for evaluating crowd detection performance.

Parameters:

• ref (str): The reference anchor points to use:
  • `

The compare() method matches detection results with ground truth across the entire database. This must be called (or eval_MR/eval_AP will call it automatically) to populate the scorelist required for evaluation.

Parameters:

• thres (float): Confidence threshold for matching (default 0.5).
• matching (str, optional): The matching strategy to use. Supported values are:
  • `

The assign_boxes_to_levels function determines which Feature Pyramid Network (FPN) level each Region of Interest (RoI) should be assigned to based on its size. It follows the logic from Equation (1) in the FPN paper, using a canonical box size and level to calculate the appropriate scale. The resulting levels are clamped between min_level and max_level to ensure they correspond to available feature maps.

# rois: Tensor of shape (N, 5) [x1, y1, x2, y2, score]
# min_level, max_level: int
# canonical_box_size: int (default 224)
# canonical_level: int (default 4)
level_assignments = assign_boxes_to_levels(rois, min_level, max_level, canonical_box_size=224, canonical_level=4)

Ensures that bounding box coordinates stay within the valid dimensions of an image. It clips the coordinates to the range [0, width-1] for x and [0, height-1] for y, while ensuring the bottom-right corner does not exceed the image boundaries.

• clip_boundary(boxes, height, width): Takes a NumPy array of boxes and the image dimensions.

import numpy as np
from lib.utils.misc_utils import clip_boundary

# boxes in [x1, y1, x2, y2] format
bboxes = np.array([[-10, -10, 1000, 1000]])
clipped = clip_boundary(bboxes, height=500, width=500)
# Result: [[0, 0, 500, 500]]

Use cpu_nms to filter overlapping bounding boxes based on a confidence score threshold. This is a pure Python implementation of the standard NMS algorithm.

Parameters:

• dets: A NumPy array of shape (N, 5) where each row represents a detection in the format [x1, y1, x2, y2, score].
• base_thr: The IoU (Intersection over Union) threshold. Boxes with an overlap greater than this value relative to a higher-scoring box will be suppressed.

Returns:

• A NumPy array of indices representing the boxes to keep.

import numpy as np
from lib.utils.nms_utils import cpu_nms

# Format: [x1, y1, x2, y2, score]
dets = np.array([
    [33, 45, 145, 230, 0.7],
    [44, 54, 123, 348, 0.8],
    [88, 12, 340, 342, 0.65]
])

base_thr = 0.5
keep_indices = cpu_nms(dets, base_thr)
keep_boxes = dets[keep_indices]

The eval_AP() method calculates the Average Precision (AP) score based on the precision-recall curve generated from the matched detections.

Returns:

• AP (float): The calculated average precision score.
• tuple: A tuple containing (rpX, rpY, thr, fpn, recalln, fppi) where:
  • rpX: Recall values.
  • rpY: Precision values.
  • thr: Threshold values.
  • fpn: False positive counts.
  • recalln: True positive counts.
  • fppi: False positives per image.

# Assuming db has been initialized and compared
AP, metrics = db.eval_AP()
print(f"Average Precision: {AP}")
# metrics contains (rpX, rpY, thr, fpn, recalln, fppi)

The device_parser function converts a string representation of device IDs into a list of integers. This is useful for specifying GPU ranges.

• If the string contains a hyphen (e.g., '0-2'), it returns a range of IDs: [0, 1, 2].
• If the string is a single integer (e.g., '0'), it returns a list containing that integer: [0].

from lib.utils.misc_utils import device_parser

ids_range = device_parser('0-2')  # [0, 1, 2]
ids_single = device_parser('1')  # [1]