cvPal
cvPal

Get Started

Dataset Structure

Learn how to organize your computer vision datasets for optimal compatibility with cvPal.

Overview

cvPal supports multiple dataset formats and structures. The recommended structure follows a clean separation of images and labels, with metadata stored in YAML configuration files. This organization ensures compatibility with popular frameworks like YOLO, COCO, and custom formats.

Basic Dataset Structure

The most common and recommended structure for cvPal datasets:

text
dataset/
├── images/
│   ├── train/
│   │   ├── image001.jpg
│   │   ├── image002.jpg
│   │   └── ...
│   ├── test/
│   │   ├── image101.jpg
│   │   ├── image102.jpg
│   │   └── ...
│   └── valid/
│       ├── image201.jpg
│       ├── image202.jpg
│       └── ...
├── labels/
│   ├── train/
│   │   ├── image001.txt
│   │   ├── image002.txt
│   │   └── ...
│   ├── test/
│   │   ├── image101.txt
│   │   ├── image102.txt
│   │   └── ...
│   └── valid/
│       ├── image201.txt
│       ├── image202.txt
│       └── ...
└── data.yaml

📁 Images Folder

Contains all image files organized by split (train/test/valid). Supports JPG, PNG, and other common formats.

🏷️ Labels Folder

Contains corresponding label files in TXT or JSON format. Each label file matches an image file.

⚙️ data.yaml

Configuration file containing dataset metadata, class names, and paths to training/validation sets.

YAML Configuration File

The data.yaml file contains essential metadata about your dataset:

Example data.yaml

yaml
# Dataset configuration
names:
  - cat
  - dog
  - bird
nc: 3  # number of classes


# Dataset paths
train: images/train
val: images/valid
test: images/test


# Optional: Additional metadata
roboflow:
  license: Private
  project: animal-detection
  url: https://universe.roboflow.com/your-project
  version: 1
  workspace: your-workspace


# Optional: Dataset info
info:
  description: "Animal detection dataset with cats, dogs, and birds"
  version: "1.0"
  created: "2024-01-01"
  author: "Your Name"

Required Fields

  • names - List of class names
  • nc - Number of classes
  • train - Path to training images
  • val - Path to validation images

Optional Fields

  • test - Path to test images
  • roboflow - Roboflow metadata
  • info - Additional dataset info

Label Formats

cvPal supports multiple label formats. Choose the one that best fits your workflow:

TXT Format (YOLO)

Each line represents one object: class_id x_center y_center width height

text
# image001.txt
0 0.5 0.3 0.2 0.4  # cat at center-left
1 0.7 0.6 0.15 0.3  # dog at bottom-right


# image002.txt
2 0.2 0.8 0.1 0.2   # bird at bottom-left

Note: All coordinates are normalized (0-1) relative to image dimensions.

JSON Format (COCO)

Structured format with detailed annotations and metadata:

json
{
  "images": [
    {
      "id": 1,
      "file_name": "image001.jpg",
      "width": 640,
      "height": 480
    }
  ],
  "annotations": [
    {
      "id": 1,
      "image_id": 1,
      "category_id": 1,
      "bbox": [100, 50, 200, 150],
      "area": 30000,
      "iscrowd": 0
    }
  ],
  "categories": [
    {
      "id": 1,
      "name": "cat",
      "supercategory": "animal"
    }
  ]
}

Alternative Structures

cvPal also supports other common dataset organizations:

Flat Structure

All images and labels in single directories:

text
dataset/
├── images/
│   ├── image001.jpg
│   ├── image002.jpg
│   └── ...
├── labels/
│   ├── image001.txt
│   ├── image002.txt
│   └── ...
└── data.yaml

Paired Structure

Images and labels in the same directory:

text
dataset/
├── image001.jpg
├── image001.txt
├── image002.jpg
├── image002.txt
└── data.yaml

Best Practices

✅ Do

  • • Use consistent naming conventions
  • • Keep images and labels synchronized
  • • Include comprehensive YAML metadata
  • • Validate label coordinates (0-1 range)
  • • Use meaningful class names
  • • Organize by train/test/valid splits

❌ Don't

  • • Mix different label formats
  • • Use absolute pixel coordinates in TXT
  • • Skip the data.yaml file
  • • Use spaces in file names
  • • Have mismatched image/label pairs
  • • Forget to update class counts

Quick Start

Using cvPal with Your Dataset

python
from cvpal.preprocessing import ImagesDetection


# Load your dataset
cp = ImagesDetection()
cp.read_data("/path/to/your/dataset", data_type="txt")


# Generate a report
cp.report()


# Merge with another dataset
cp.merge_datasets([
    "/path/to/dataset1",
    "/path/to/dataset2"
])
InstallationSupported Models