---

name: image-ai description: "Use ImageAI 3.x PyTorch computer-vision workflows for classification, object detection, video detection, and custom training." disable-model-invocation: true metadata: disco-role: operating license: MIT

ImageAI Repo Skill

Use this repo skill when a task involves the ImageAI Python package (imageai), especially ImageAI 3.x PyTorch workflows for simple computer-vision applications.

Start here

1. Confirm the user is using ImageAI 3.x / PyTorch assets (.pt or .pth). TensorFlow/Keras .h5 models are legacy ImageAI 2.x artifacts and are not accepted by the current package path.
2. Confirm local model weights, images/videos, datasets, and JSON config files exist. This skill does not bundle pretrained weights or download assets.
3. Choose the closest sub-skill route below.
4. For environment uncertainty, run the bundled smoke checker before loading large weights:

python scripts/check_imageai_env.py
python scripts/check_imageai_env.py --require-cuda

Route by task

User task	Read
Classify a still image with ImageNet weights	classification-workflows
Run custom image classification from a trained .pt/.pth model and classes JSON	classification-workflows
Detect COCO objects in a still image with RetinaNet, YOLOv3, or TinyYOLOv3	object-detection-workflows
Run custom YOLO/TinyYOLO still-image detection from a trained model and detection JSON	object-detection-workflows
Detect objects in videos, camera feeds, or live streams	video-detection-workflows
Add per-frame, per-second, per-minute, or whole-video analysis callbacks	video-detection-workflows
Prepare datasets, convert Pascal VOC to YOLO, validate layouts, or start custom training	custom-training-and-data
Resolve install, backend, or model-asset confusion	installation and model assets and troubleshooting

Package and install essentials

ImageAI 3.x uses PyTorch. A typical CPU-oriented setup follows the package docs and requirements:

pip install imageai
pip install cython "pillow>=7.0.0" "numpy>=1.18.1" "opencv-python>=4.1.2" \
  "torch>=1.9.0" "torchvision>=0.10.0" tqdm scipy matplotlib mock

Use a PyTorch CUDA wheel only when the runtime has compatible NVIDIA drivers and the task needs acceleration. CUDA is helpful for video and real training, but CPU is enough for import/API checks and small validation helpers. See installation and model assets for dependency variants, model-weight expectations, and legacy TensorFlow notes.

Minimal import/API check

from imageai.Classification import ImageClassification
from imageai.Detection import ObjectDetection, VideoObjectDetection
from imageai.Classification.Custom import ClassificationModelTrainer, CustomImageClassification
from imageai.Detection.Custom import DetectionModelTrainer, CustomObjectDetection, CustomVideoObjectDetection

for cls in [
    ImageClassification, ObjectDetection, VideoObjectDetection,
    ClassificationModelTrainer, CustomImageClassification,
    DetectionModelTrainer, CustomObjectDetection, CustomVideoObjectDetection,
]:
    cls()

If this fails, do not proceed to weight loading. Use the root troubleshooting reference first.

Shared operating rules

• Always choose the model-type setter that matches the weight architecture. Filenames are hints, not proof.
• Current ImageAI 3.x model files must be .pt or .pth; .h5 triggers a TensorFlow-legacy error.
• Call useCPU() before loadModel() when forcing CPU.
• Load large weights once and reuse the detector/classifier object for repeated images or frames.
• Treat pretrained weights, custom models, JSON mappings, datasets, videos, and camera streams as caller-supplied assets.
• Do not run full video detection or training as a quick smoke test unless the user supplies bounded assets and compute expectations.

Provenance and routing metadata

• repo-provenance.md records the source snapshot and evidence paths used to create this skill.
• repo-routing-metadata.json records managed repo-skills-router placement for import tooling.