include steps for ai-hub

examples/meter-detection/README.md

@@ -0,0 +1,271 @@
+# YOLO26 Electric Meter Detection Example
+
+This example trains a YOLO26 object detection model on the Roboflow Universe electric meter dataset using the existing `qc-cli` SageMaker training flow.
+
+The workflow is intentionally command driven. Run each step yourself so you can inspect the dataset, update `config.yaml`, and decide when to submit the SageMaker job.
+
+Dataset:
+
+```text
+https://universe.roboflow.com/kemals-workspace-kbc8l/electric-meter-detection-o4tfi/dataset/1
+```
+
+## Prerequisites
+
+- Install or sync the project dependencies: `uv sync`
+- The virtual environment is activated.
+- AWS credentials configured for the profile in `config.yaml`
+- Infrastructure already deployed with `qc-cli infra setup`
+
+## 1. Download The Dataset
+
+Register or sign in to Roboflow, then open the dataset page:
+
+```text
+https://universe.roboflow.com/kemals-workspace-kbc8l/electric-meter-detection-o4tfi/dataset/1
+```
+
+Download the dataset in YOLOv26 format from the Roboflow UI, then extract the downloaded archive into:
+
+```text
+examples/meter-detection/data/electric-meter-detection
+```
+
+The `data.yaml` file should be directly under that folder:
+
+```text
+examples/meter-detection/data/electric-meter-detection/data.yaml
+```
+
+Do not move `data.yaml` into the `train/` split folder.
+
+After extracting, confirm the dataset has a YOLO data file and image splits:
+
+```bash
+find examples/meter-detection/data/electric-meter-detection -maxdepth 2 -type d | sort
+find examples/meter-detection/data/electric-meter-detection -name data.yaml -print
+```
+
+Open `examples/meter-detection/data/electric-meter-detection/data.yaml` and make sure the split paths are relative to that folder:
+
+```yaml
+path: .
+train: train/images
+val: valid/images
+test: test/images
+```
+
+If your downloaded dataset does not include a `test/` folder, remove the `test:` line.
+
+The expected layout is similar to:
+
+```text
+examples/meter-detection/data/electric-meter-detection/
+  data.yaml
+  train/
+  valid/
+  test/
+```
+
+## 2. Configure SageMaker Training
+
+Update `config.yaml` so the training section points at this example's source directory:
+
+```yaml
+sagemaker:
+  training:
+    image_uri: 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-training:2.6-cpu-py312-ubuntu22.04-sagemaker-v1
+    instance_type: ml.g4dn.xlarge
+    instance_count: 1
+    source_dir: examples/meter-detection/source
+    entry_point: train.py
+    hyperparameters:
+      model: yolo26n.pt
+      epochs: 25
+      imgsz: 640
+      batch: 16
+      workers: 2
+```
+
+Use `yolo26n.pt` for a lightweight first YOLO26 run. If those weights are unavailable in the installed Ultralytics package, use `yolo11n.pt` as the established fallback:
+
+```yaml
+      model: yolo11n.pt
+```
+
+The `source/requirements.txt` file is installed by the SageMaker PyTorch container before running `train.py`.
+
+For a CPU smoke test, use a CPU instance and reduce the workload:
+
+```yaml
+sagemaker:
+  training:
+    image_uri: 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-training:2.6-cpu-py312-ubuntu22.04-sagemaker-v1
+    instance_type: ml.m4.xlarge
+    instance_count: 1
+    source_dir: examples/meter-detection/source
+    entry_point: train.py
+    hyperparameters:
+      model: yolo26n.pt
+      epochs: 1
+      imgsz: 320
+      batch: 4
+      workers: 2
+```
+
+## 3. Check Infrastructure
+
+Confirm the CLI can see the configured SageMaker role and S3 bucket:
+
+```bash
+qc-cli infra status
+```
+
+## 4. Upload The Dataset
+
+Upload the downloaded Roboflow dataset to the `s3.data_prefix` configured in `config.yaml`:
+
+```bash
+qc-cli upload examples/meter-detection/data/electric-meter-detection
+```
+
+Directory uploads preserve paths relative to the uploaded directory, so SageMaker receives the dataset root with `data.yaml` plus the split directories.
+
+In SageMaker, this uploaded dataset root is mounted at `/opt/ml/input/data/train`. That `train` path is the SageMaker channel name, not the YOLO `train/` split folder.
+
+## 5. Start Training
+
+Submit the SageMaker training job:
+
+```bash
+qc-cli train start
+```
+
+The command prints the submitted SageMaker job name. Check progress with:
+
+```bash
+qc-cli train status
+```
+
+Or pass the job name explicitly:
+
+```bash
+qc-cli train status qc-cli-YYYYMMDD-HHMMSS
+```
+
+## SageMaker Outputs
+
+When the job completes, SageMaker packages the files written under `/opt/ml/model` into `model.tar.gz`.
+
+This example writes:
+
+```text
+best.pt
+model.onnx
+metrics.json
+```
+
+The archive is stored under the configured `s3.model_prefix`.
+
+## 6. Configure Qualcomm AI Hub
+
+Authenticate with Qualcomm AI Hub:
+
+```bash
+qai-hub configure --api_token
+```
+
+Add AI Hub settings to `config.yaml`. The input name and image size must match the ONNX model exported by this example:
+
+```yaml
+aihub:
+  device:
+    name: Dragonwing IQ-9075 EVK
+  target_runtime: tflite
+  input_specs:
+    images: [[1, 3, 640, 640], float32]
+  job_name: meter-detection
+  model_name: meter-detection
+  output_dir: build/qai-hub/meter-detection
+```
+
+Use the same image size configured in `sagemaker.training.hyperparameters.imgsz`. For example, a smoke-test model
+trained with `imgsz: 320` requires `images: [[1, 3, 320, 320], float32]`.
+
+## 7. Prepare AI Hub Inputs
+
+Generate calibration samples and a validation input from the downloaded dataset:
+
+```bash
+uv run python examples/meter-detection/prepare_aihub_inputs.py --image-size 640
+```
+
+This writes:
+
+```text
+examples/meter-detection/data/aihub_calibration/*.npy
+examples/meter-detection/data/inputs.npz
+```
+
+The script applies the preprocessing expected by the exported YOLO model: aspect-ratio-preserving letterboxing,
+RGB channel order, channel-first layout, and pixel values normalized to `[0, 1]`.
+
+Set `--image-size` to the training `imgsz` value when it is not `640`.
+
+## 8. Upload To Qualcomm AI Hub
+
+Use the SageMaker job name printed by `qc-cli train start`:
+
+```bash
+qc-cli ai-hub upload \
+  examples/meter-detection/data/aihub_calibration \
+  examples/meter-detection/data/inputs.npz \
+  --from-job qc-cli-YYYYMMDD-HHMMSS
+```
+
+The command downloads the job's `model.tar.gz`, finds `model.onnx`, uploads it to AI Hub, and runs quantization,
+compilation, validation, and profiling. The uploaded source model uses the configured
+`aihub.model_name`.
+
+If the meter-detection job is still the last training job in `.qc-cli.json`, `--from-job` can be omitted. Keeping it
+explicit prevents accidentally uploading an artifact from a different training run.
+
+To resume after a completed step, use one of:
+
+```bash
+qc-cli ai-hub upload \
+  examples/meter-detection/data/aihub_calibration \
+  examples/meter-detection/data/inputs.npz \
+  --from-step compile
+```
+
+```bash
+qc-cli ai-hub upload \
+  examples/meter-detection/data/aihub_calibration \
+  examples/meter-detection/data/inputs.npz \
+  --from-step validate
+```
+
+Download the compiled artifact after the workflow completes:
+
+```bash
+qc-cli ai-hub download --output build/qai-hub/meter-detection/model.tflite
+```
+
+## Training Hyperparameters
+
+Values under `sagemaker.training.hyperparameters` are passed to `source/train.py` as command-line arguments.
+
+| Name | Type | Default | Description |
+|---|---:|---:|---|
+| `model` | string | `yolo26n.pt` | Ultralytics model weights or model YAML. |
+| `epochs` | int | `25` | Number of training epochs. |
+| `imgsz` | int | `640` | Square training image size. |
+| `batch` | int | `16` | Images per training batch. |
+| `workers` | int | `2` | DataLoader worker count. |
+| `patience` | int | `20` | Early stopping patience. |
+| `device` | string | auto | Optional Ultralytics device value such as `0` or `cpu`. |
+| `data-yaml` | string | auto | Optional path to `data.yaml`; normally discovered from the uploaded dataset root. |
+| `dataset-dir` | string | `SM_CHANNEL_TRAIN` | Uploaded dataset root mounted by SageMaker. |
+
+Do not set `dataset-dir` or `model-dir` in normal SageMaker runs. SageMaker sets those automatically through `SM_CHANNEL_TRAIN` and `SM_MODEL_DIR`.

examples/meter-detection/prepare_aihub_inputs.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Prepare Qualcomm AI Hub calibration and validation inputs for the meter detector."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png"}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--dataset-dir",
+        type=Path,
+        default=Path("examples/meter-detection/data/electric-meter-detection"),
+        help="Root of the extracted Roboflow dataset.",
+    )
+    parser.add_argument(
+        "--calibration-dir",
+        type=Path,
+        default=Path("examples/meter-detection/data/aihub_calibration"),
+        help="Directory where .npy calibration samples will be written.",
+    )
+    parser.add_argument(
+        "--input-file",
+        type=Path,
+        default=Path("examples/meter-detection/data/inputs.npz"),
+        help="Validation .npz input file for qc-cli ai-hub validate.",
+    )
+    parser.add_argument("--input-name", default="images", help="ONNX input name.")
+    parser.add_argument("--image-size", type=int, default=640, help="Square image size used for ONNX export.")
+    parser.add_argument("--samples", type=int, default=16, help="Number of calibration samples to write.")
+    return parser.parse_args()
+
+
+def preprocess_image(path: Path, image_size: int) -> np.ndarray:
+    """Apply Ultralytics-style letterboxing and produce an NCHW float32 tensor."""
+    with Image.open(path) as source:
+        image = source.convert("RGB")
+
+    scale = min(image_size / image.width, image_size / image.height)
+    resized_width = round(image.width * scale)
+    resized_height = round(image.height * scale)
+    image = image.resize((resized_width, resized_height), Image.Resampling.BILINEAR)
+
+    canvas = Image.new("RGB", (image_size, image_size), (114, 114, 114))
+    left = round((image_size - resized_width) / 2 - 0.1)
+    top = round((image_size - resized_height) / 2 - 0.1)
+    canvas.paste(image, (left, top))
+
+    array = np.asarray(canvas, dtype=np.float32) / 255.0
+    return np.transpose(array, (2, 0, 1))[None, ...].astype(np.float32)
+
+
+def main() -> None:
+    args = parse_args()
+    if args.image_size < 1:
+        raise SystemExit("--image-size must be at least 1")
+    if args.samples < 1:
+        raise SystemExit("--samples must be at least 1")
+
+    images = sorted(
+        path
+        for path in args.dataset_dir.rglob("*")
+        if path.is_file() and path.suffix.lower() in IMAGE_EXTENSIONS and path.parent.name == "images"
+    )
+    if not images:
+        raise SystemExit(f"No images found under {args.dataset_dir}")
+
+    args.calibration_dir.mkdir(parents=True, exist_ok=True)
+    args.input_file.parent.mkdir(parents=True, exist_ok=True)
+    for stale_sample in args.calibration_dir.glob("sample_*.npy"):
+        stale_sample.unlink()
+
+    prepared: list[np.ndarray] = []
+    for index, image_path in enumerate(images[: args.samples]):
+        sample = preprocess_image(image_path, args.image_size)
+        np.save(args.calibration_dir / f"sample_{index:03d}.npy", sample)
+        prepared.append(sample)
+
+    np.savez(args.input_file, **{args.input_name: prepared[0]})  # pyright: ignore[reportArgumentType]
+    print(f"Wrote {len(prepared)} calibration samples to {args.calibration_dir}")
+    print(f"Wrote validation input to {args.input_file}")
+
+
+if __name__ == "__main__":
+    main()

examples/meter-detection/source/requirements.txt

@@ -0,0 +1,3 @@
+ultralytics>=8.3.0
+pyyaml>=6.0.3
+onnx>=1.16.0

examples/meter-detection/source/train.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""SageMaker entry point for YOLO electric meter detection training."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+from pathlib import Path
+from typing import Any
+
+import yaml
+from ultralytics import YOLO  # type: ignore[reportMissingImports]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--model", default="yolo26n.pt")
+    parser.add_argument("--epochs", type=int, default=25)
+    parser.add_argument("--imgsz", type=int, default=640)
+    parser.add_argument("--batch", type=int, default=16)
+    parser.add_argument("--workers", type=int, default=2)
+    parser.add_argument("--patience", type=int, default=20)
+    parser.add_argument("--device", default=None)
+    parser.add_argument("--data-yaml", default=None)
+    parser.add_argument("--dataset-dir", default=os.environ.get("SM_CHANNEL_TRAIN", "/opt/ml/input/data/train"))
+    parser.add_argument("--train-dir", dest="dataset_dir", help=argparse.SUPPRESS)
+    parser.add_argument("--model-dir", default=os.environ.get("SM_MODEL_DIR", "/opt/ml/model"))
+    return parser.parse_args()
+
+
+def find_data_yaml(dataset_dir: Path, explicit_path: str | None) -> Path:
+    if explicit_path:
+        data_yaml = Path(explicit_path)
+        if data_yaml.is_file():
+            return data_yaml
+        raise FileNotFoundError(f"Configured data.yaml does not exist: {data_yaml}")
+
+    matches = sorted(dataset_dir.rglob("data.yaml"))
+    if not matches:
+        raise FileNotFoundError(f"Could not find data.yaml under {dataset_dir}")
+    if len(matches) > 1:
+        print(f"Found multiple data.yaml files; using {matches[0]}")
+    return matches[0]
+
+
+def prepare_data_yaml(data_yaml: Path) -> Path:
+    """Write a SageMaker-local data file rooted at the uploaded dataset."""
+    dataset_root = data_yaml.parent
+    data = yaml.safe_load(data_yaml.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected a mapping in {data_yaml}")
+
+    normalized = dict(data)
+    normalized["path"] = str(dataset_root)
+    if "val" not in normalized and "valid" in normalized:
+        normalized["val"] = normalized.pop("valid")
+
+    prepared_path = dataset_root / "data.sagemaker.yaml"
+    prepared_path.write_text(yaml.safe_dump(normalized, sort_keys=False), encoding="utf-8")
+    print(f"Prepared dataset config: {prepared_path}")
+    return prepared_path
+
+
+def copy_if_exists(source: Path, destination: Path) -> None:
+    if source.exists():
+        shutil.copy2(source, destination)
+        print(f"Saved {destination}")
+
+
+def main() -> None:
+    args = parse_args()
+    dataset_dir = Path(args.dataset_dir)
+    model_dir = Path(args.model_dir)
+    model_dir.mkdir(parents=True, exist_ok=True)
+
+    data_yaml = prepare_data_yaml(find_data_yaml(dataset_dir, args.data_yaml))
+    model = YOLO(args.model)
+
+    train_kwargs: dict[str, Any] = {
+        "data": str(data_yaml),
+        "epochs": args.epochs,
+        "imgsz": args.imgsz,
+        "batch": args.batch,
+        "workers": args.workers,
+        "patience": args.patience,
+        "project": str(model_dir / "runs"),
+        "name": "train",
+        "exist_ok": True,
+    }
+    if args.device:
+        train_kwargs["device"] = args.device
+
+    results = model.train(**train_kwargs)
+    save_dir = Path(results.save_dir)
+    best_pt = save_dir / "weights" / "best.pt"
+    last_pt = save_dir / "weights" / "last.pt"
+    trained_weights = best_pt if best_pt.exists() else last_pt
+    if not trained_weights.exists():
+        raise FileNotFoundError(f"Could not find trained weights in {save_dir / 'weights'}")
+
+    copy_if_exists(trained_weights, model_dir / "best.pt")
+    trained_model = YOLO(str(trained_weights))
+    onnx_path = Path(trained_model.export(format="onnx", imgsz=args.imgsz))
+    copy_if_exists(onnx_path, model_dir / "model.onnx")
+
+    metrics = {
+        "model": args.model,
+        "epochs": args.epochs,
+        "imgsz": args.imgsz,
+        "batch": args.batch,
+        "workers": args.workers,
+        "patience": args.patience,
+        "data_yaml": str(data_yaml),
+        "weights": str(trained_weights),
+        "onnx": str(onnx_path),
+    }
+    (model_dir / "metrics.json").write_text(json.dumps(metrics, indent=2), encoding="utf-8")
+    print(f"Saved model artifacts to {model_dir}")
+
+
+if __name__ == "__main__":
+    main()