mblt-vision-python 0.0.0__py3-none-any.whl

mblt_vision/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface for standalone Mobilint Vision workflows."""
+
+from .main import build_parser, main
+
+__all__ = ["build_parser", "main"]

mblt_vision/cli/__main__.py

@@ -0,0 +1,5 @@
+"""Run the standalone Vision CLI with ``python -m mblt_vision.cli``."""
+
+from .main import main
+
+raise SystemExit(main())

mblt_vision/cli/_vision.py

@@ -0,0 +1,337 @@
+"""Shared helpers for vision CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import torch
+from mblt_vision._tasks import normalize_vision_task
+
+DEFAULT_OUTPUT_DIR = Path("runs") / "vision"
+
+
+def parse_unit_interval(value: str) -> float:
+    """Parse a floating-point value strictly between zero and one."""
+
+    try:
+        parsed = float(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            "expected a number in the open interval (0, 1)"
+        ) from exc
+    if not 0 < parsed < 1:
+        raise argparse.ArgumentTypeError(
+            f"expected a number in the open interval (0, 1), got {value}"
+        )
+    return parsed
+
+
+def parse_target_cores(value: str | None) -> list[str] | None:
+    """Parses a semicolon-separated target core list."""
+
+    if value is None:
+        return None
+    cores = [item.strip() for item in value.split(";") if item.strip()]
+    return cores or None
+
+
+def parse_target_clusters(value: str | None) -> list[int] | None:
+    """Parses a semicolon-separated target cluster list."""
+
+    if value is None:
+        return None
+    try:
+        clusters = [int(item.strip()) for item in value.split(";") if item.strip()]
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            "target clusters must be semicolon-separated integers"
+        ) from exc
+    return clusters or None
+
+
+def add_common_vision_args(parser: argparse.ArgumentParser) -> None:
+    """Adds arguments shared by all vision inference commands."""
+
+    parser.add_argument("--source", required=True, help="Path to the source image.")
+    parser.add_argument(
+        "--model",
+        required=True,
+        help="Vision model name, for example `resnet50` or `yolo11m`.",
+    )
+    parser.add_argument(
+        "--output",
+        "--save-path",
+        dest="output",
+        help="Path to save the plotted result image.",
+    )
+    parser.add_argument(
+        "--framework",
+        default=None,
+        choices=["mxq", "onnx"],
+        help="Inference framework to use. When omitted, `--model-path` suffix is used first, then `mxq`.",
+    )
+    parser.add_argument(
+        "--model-path",
+        dest="model_path",
+        default="",
+        help="Optional generic local model path for MXQ or ONNX inference.",
+    )
+    parser.add_argument(
+        "--mxq-path",
+        dest="mxq_path",
+        default="",
+        help="Optional local MXQ model path. Preserved as a compatibility alias.",
+    )
+    parser.add_argument(
+        "--onnx-path",
+        dest="onnx_path",
+        default="",
+        help="Optional local ONNX model path.",
+    )
+    parser.add_argument(
+        "--model-type",
+        default="DEFAULT",
+        help="Model variant from the YAML configuration.",
+    )
+    parser.add_argument(
+        "--core-mode",
+        default=None,
+        choices=["single", "multi", "global4", "global8"],
+        help="NPU core execution mode. Defaults to global8 on Aries and single on Regulus.",
+    )
+    parser.add_argument("--dev-no", type=int, default=0, help="NPU device number.")
+    parser.add_argument(
+        "--target-device",
+        default="aries-rb",
+        choices=["aries-rb", "regulus-ra", "regulus-rb"],
+        help="NPU board target. Determines the backend implementation.",
+    )
+    parser.add_argument(
+        "--target-cores",
+        type=parse_target_cores,
+        help="Optional semicolon-separated core list for single-core mode, for example `0:0;0:1`.",
+    )
+    parser.add_argument(
+        "--target-clusters",
+        type=parse_target_clusters,
+        help="Optional semicolon-separated cluster list for multi/global modes, for example `0;1`.",
+    )
+
+
+def add_threshold_args(
+    parser: argparse.ArgumentParser,
+    *,
+    conf_default: float | None = 0.25,
+    iou_default: float | None = None,
+) -> None:
+    """Adds postprocess threshold arguments for dense vision tasks."""
+
+    parser.add_argument(
+        "--conf-thres",
+        type=parse_unit_interval,
+        default=conf_default,
+        help="Confidence threshold.",
+    )
+    parser.add_argument(
+        "--iou-thres",
+        type=parse_unit_interval,
+        default=iou_default,
+        help="IoU threshold.",
+    )
+
+
+def parse_bool(value: str) -> bool:
+    """Parses a case-insensitive boolean CLI value.
+
+    Args:
+        value: Boolean text to parse.
+
+    Returns:
+        Parsed boolean value.
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is not a supported boolean spelling.
+    """
+
+    normalized = value.strip().lower()
+    if normalized in {"true", "1", "yes", "on"}:
+        return True
+    if normalized in {"false", "0", "no", "off"}:
+        return False
+    raise argparse.ArgumentTypeError("expected a boolean value: true or false")
+
+
+def add_e2e_arg(parser: argparse.ArgumentParser) -> None:
+    """Adds an optional YOLO end-to-end postprocessing mode override.
+
+    Leaving the option unset preserves the model configuration's default.
+    """
+
+    parser.add_argument(
+        "--e2e",
+        nargs="?",
+        const=True,
+        type=parse_bool,
+        default=None,
+        help="Enable or disable YOLO end-to-end postprocessing (true/false). Bare `--e2e` means true.",
+    )
+
+
+def add_vision_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+    *,
+    command: str,
+    help_text: str,
+    handler: Any,
+    description: str | None = None,
+    epilog: str | None = None,
+) -> argparse.ArgumentParser:
+    """Creates a vision command parser with common arguments."""
+
+    parser = subparsers.add_parser(
+        command,
+        help=help_text,
+        description=description,
+        epilog=epilog,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.set_defaults(_handler=handler)
+    add_common_vision_args(parser)
+    return parser
+
+
+def build_default_output_path(command: str, source: str, model: str) -> str:
+    """Builds the default path used for plotted vision command output."""
+
+    source_path = Path(source)
+    suffix = source_path.suffix or ".jpg"
+    return str(DEFAULT_OUTPUT_DIR / command / f"{source_path.stem}_{model}{suffix}")
+
+
+def resolve_output_path(
+    output: str | None, command: str, source: str, model: str
+) -> str:
+    """Returns an absolute result image path and ensures its parent exists."""
+
+    save_path = Path(
+        output or build_default_output_path(command, source, model)
+    ).expanduser()
+    save_path.parent.mkdir(parents=True, exist_ok=True)
+    return str(save_path.resolve())
+
+
+def require_source_file(source: str) -> None:
+    """Exits with a clear message when the source image is unavailable."""
+
+    source_path = Path(source).expanduser()
+    if not source_path.is_file():
+        raise SystemExit(f"Source image not found: {source}")
+
+
+def create_vision_engine(args: argparse.Namespace) -> Any:
+    """Creates a vision engine from shared CLI model options.
+
+    Args:
+        args: Parsed command options containing common vision model arguments.
+
+    Returns:
+        Initialized vision inference engine.
+
+    Raises:
+        SystemExit: If the vision runtime dependencies are unavailable.
+    """
+
+    try:
+        from mblt_vision import MBLT_Engine
+        from mblt_vision.wrapper import normalize_core_mode
+    except ImportError as exc:
+        print(f"Missing dependencies for vision CLI: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc
+
+    postprocess_kwargs: dict[str, Any] = {}
+    if getattr(args, "e2e", None) is not None:
+        postprocess_kwargs["e2e"] = args.e2e
+
+    return MBLT_Engine(
+        model_cls=args.model,
+        model_type=args.model_type,
+        framework=args.framework,
+        model_path=args.model_path,
+        mxq_path=args.mxq_path,
+        onnx_path=args.onnx_path,
+        dev_no=args.dev_no,
+        target_device=args.target_device,
+        core_mode=normalize_core_mode(
+            args.core_mode
+            or ("single" if args.target_device.startswith("regulus-") else "global8")
+        ),
+        target_cores=args.target_cores,
+        target_clusters=args.target_clusters,
+        postprocess_kwargs=postprocess_kwargs,
+    )
+
+
+def run_vision_inference(
+    args: argparse.Namespace,
+    *,
+    command: str,
+) -> Any:
+    """Runs a complete vision inference pipeline for a CLI command."""
+
+    require_source_file(args.source)
+    model = create_vision_engine(args)
+    try:
+        actual_task = normalize_vision_task(model.post_cfg.get("task", ""))
+        plot_kwargs: dict[str, Any] = {}
+        if actual_task == "image_classification":
+            plot_kwargs["topk"] = args.topk
+        elif actual_task in {
+            "object_detection",
+            "face_detection",
+            "instance_segmentation",
+            "pose_estimation",
+            "obb",
+        }:
+            model.set_postprocess_thresholds(
+                conf_thres=args.conf_thres, iou_thres=args.iou_thres
+            )
+
+        postprocess_kwargs: dict[str, Any] = {}
+        if actual_task == "semantic_segmentation":
+            input_img, metadata = model.preprocess_with_metadata(args.source)
+            postprocess_kwargs["img0_shape"] = metadata["img0_shape"]
+            postprocess_kwargs["ratio_pad"] = metadata.get("ratio_pad")
+        else:
+            input_img = model.preprocess(args.source)
+        output = model(input_img)
+        if not getattr(getattr(model, "postprocessor", None), "e2e", True):
+            if args.output:
+                raise SystemExit(
+                    "`--output` is unavailable with `--e2e false`; use `--raw-output` instead."
+                )
+
+            raw_output = model.postprocessor(output)
+            raw_output_path = getattr(args, "raw_output", None)
+            if raw_output_path:
+                output_path = Path(raw_output_path).expanduser()
+                output_path.parent.mkdir(parents=True, exist_ok=True)
+                torch.save(raw_output, output_path)
+                print(f"Saved raw postprocess output to {output_path}")
+            else:
+                print(
+                    "Generated raw export-style postprocess output. Use `--raw-output` to save it."
+                )
+            return raw_output
+
+        result = model.postprocess(output, **postprocess_kwargs)
+
+        save_path = resolve_output_path(args.output, command, args.source, args.model)
+        result.plot(source_path=args.source, save_path=save_path, **plot_kwargs)
+        print(f"Saved result to {os.path.relpath(save_path)}")
+        return result
+    finally:
+        model.dispose()

mblt_vision/cli/compile.py

@@ -0,0 +1,117 @@
+"""Vision compilation CLI command."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def _run_compile(args: argparse.Namespace) -> int:
+    """Compile a vision model from parsed CLI arguments.
+
+    Args:
+        args: Parsed compilation arguments.
+
+    Returns:
+        Successful process status.
+    """
+
+    try:
+        from mblt_vision.compile import compile_vision_model
+
+        output_path = compile_vision_model(
+            model_cls=args.model_cls,
+            target_device=args.target_device,
+            model_type=args.model_type,
+            model_path=args.model_path,
+            data_path=args.data_path,
+            subset_path=args.subset_path,
+            calib_data_path=args.calib_data_path,
+            save_path=args.save_path,
+            subset_size=args.subset_size,
+            seed=args.seed,
+            percentile=args.percentile,
+            topk_ratio=args.topk_ratio,
+        )
+    except ImportError as exc:
+        print(str(exc), file=sys.stderr)
+        raise SystemExit(2) from exc
+    print(f"Compiled MXQ model to {output_path}")
+    return 0
+
+
+def add_compile_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> argparse.ArgumentParser:
+    """Register the vision compilation command.
+
+    Args:
+        subparsers: Main CLI subparser collection.
+
+    Returns:
+        Registered compile command parser.
+    """
+
+    parser = subparsers.add_parser(
+        "compile", help="Compile a configured vision ONNX model to MXQ."
+    )
+    parser.set_defaults(_handler=_run_compile)
+    parser.add_argument(
+        "--model-cls",
+        required=True,
+        help="Vision model name, for example `alexnet` or `yolo11m`.",
+    )
+    parser.add_argument(
+        "--target-device",
+        required=True,
+        choices=["aries-rb", "regulus-ra", "regulus-rb"],
+        help="Required NPU board target for the compiled MXQ artifact.",
+    )
+    parser.add_argument(
+        "--model-type",
+        default="DEFAULT",
+        help="Model variant from the YAML configuration.",
+    )
+    parser.add_argument(
+        "--model-path",
+        "--onnx-path",
+        dest="model_path",
+        help="Preferred local ONNX file. Missing files fall back to the configured hosted artifact.",
+    )
+    data_group = parser.add_mutually_exclusive_group()
+    data_group.add_argument(
+        "--data-path",
+        help="Original organized dataset root; organize, sample, and preprocess it as needed.",
+    )
+    data_group.add_argument(
+        "--subset-path",
+        help="Already-sampled image subset; skip original dataset preparation and sampling.",
+    )
+    data_group.add_argument(
+        "--calib-data-path",
+        "--calib-data-dir",
+        dest="calib_data_path",
+        help="Ready directory of preprocessed .npy tensors; pass it directly to qbcompiler.",
+    )
+    parser.add_argument(
+        "--save-path",
+        help="Output MXQ path. Defaults to the ONNX stem under ~/.mblt_model_zoo.",
+    )
+    parser.add_argument(
+        "--subset-size",
+        type=int,
+        help="Per-category ImageNet/WiderFace count or total count for other datasets.",
+    )
+    parser.add_argument(
+        "--seed", type=int, default=0, help="Deterministic calibration subset seed."
+    )
+    parser.add_argument(
+        "--percentile", type=float, help="Quantization percentile override."
+    )
+    parser.add_argument(
+        "--topk-ratio", type=float, help="Quantization top-k ratio override."
+    )
+    return parser
+
+
+__all__ = ["add_compile_parser"]

mblt_vision/cli/main.py

@@ -0,0 +1,35 @@
+"""Standalone command-line entry point for Mobilint Vision."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from .compile import add_compile_parser
+from .predict import add_predict_parser
+from .val import add_val_parser
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the standalone Vision command parser."""
+
+    parser = argparse.ArgumentParser(
+        prog="mblt-vision",
+        description="Run, validate, and compile Mobilint Vision models.",
+    )
+    subparsers = parser.add_subparsers(help="mblt-vision commands")
+    add_predict_parser(subparsers)
+    add_val_parser(subparsers)
+    add_compile_parser(subparsers)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the standalone Vision command-line interface."""
+
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if hasattr(args, "_handler"):
+        return int(args._handler(args))
+    parser.print_help()
+    return 1

mblt_vision/cli/predict.py

@@ -0,0 +1,64 @@
+"""Vision prediction CLI command."""
+
+from __future__ import annotations
+
+import argparse
+
+from ._vision import (
+    add_e2e_arg,
+    add_threshold_args,
+    add_vision_parser,
+    run_vision_inference,
+)
+
+
+def _cmd_predict(args: argparse.Namespace) -> int:
+    """Runs vision inference on a source image."""
+
+    run_vision_inference(args, command="predict")
+    return 0
+
+
+def add_predict_parser(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    """Registers the unified vision prediction CLI command."""
+
+    parser = add_vision_parser(
+        subparsers,
+        command="predict",
+        help_text=(
+            "Run vision inference for classification, depth estimation, detection, instance or semantic "
+            "segmentation, OBB, pose, and face detection."
+        ),
+        description=(
+            "Run a configured Vision model on one image. The selected model determines the task, "
+            "preprocessing, postprocessing, and output visualization automatically."
+        ),
+        epilog="""Supported tasks:
+  image classification, depth estimation, object and face detection, instance
+  and semantic segmentation, oriented bounding boxes (OBB), and pose estimation.
+
+The command downloads the default MXQ artifact when no local model path is supplied,
+then writes a plotted result under runs/vision/predict/ by default. Use --output to
+choose the image destination. Use --framework onnx with --model-path or --onnx-path
+for ONNX Runtime inference; MXQ is the default framework.
+
+Examples:
+  mblt-vision predict --source image.jpg --model resnet50 --topk 3
+  mblt-vision predict --source image.jpg --model yolo11m --conf-thres 0.4 --output result.jpg
+  mblt-vision predict --source image.jpg --model yolo11m --framework onnx
+  mblt-vision predict --source image.jpg --model yolo11m-pose --target-device regulus-ra --core-mode single
+
+For export-style YOLO output, use --e2e false and optionally save it with --raw-output.""",
+        handler=_cmd_predict,
+    )
+    parser.add_argument(
+        "--topk", type=int, default=5, help="Number of classification labels to show."
+    )
+    parser.add_argument(
+        "--raw-output",
+        help="Path to save raw export-style output with `--e2e false`.",
+    )
+    add_threshold_args(parser, conf_default=0.25, iou_default=None)
+    add_e2e_arg(parser)