Add tests and docs

Author: kipcole9

README.md

@@ -2,122 +2,118 @@
 
 `ImageVision` is a simple, opinionated image vision library for Elixir. It sits alongside the [`image`](https://hex.pm/packages/image) library and answers three questions about any image — **what's in it**, **where are the objects**, and **which pixels belong to which object** — with strong defaults and no ML expertise required.
 
-## Tasks
-
-| Task | Module | What it does |
-|---|---|---|
-| Classification | [`Image.Classification`](https://hexdocs.pm/image_vision/Image.Classification.html) | Labels like `"sports car"` or `"Blenheim spaniel"` |
-| Embedding | [`Image.Classification`](https://hexdocs.pm/image_vision/Image.Classification.html) | 768-dim feature vector for similarity search |
-| Segmentation | [`Image.Segmentation`](https://hexdocs.pm/image_vision/Image.Segmentation.html) | Pixel masks — promptable ("cut out this object") or class-labeled ("every region in the image") |
-| Detection | [`Image.Detection`](https://hexdocs.pm/image_vision/Image.Detection.html) | Bounding boxes with class labels |
-
-## Installation
+## Quick start
 
 ```elixir
-def deps do
-  [
-    {:image_vision, "~> 0.2"},
-    # Nx backend for classification (pick one)
-    {:exla, "~> 0.9"},
-    # Required for classification
-    {:bumblebee, "~> 0.6"},
-    # Required for segmentation and detection
-    {:ortex, "~> 0.1"}
-  ]
-end
-```
-
-## Quick examples
-
-```elixir
-# Classification — what's in this image?
+# Classification — what is in this image?
 iex> puppy = Image.open!("puppy.jpg")
 iex> Image.Classification.labels(puppy)
 ["Blenheim spaniel"]
 
-# Embedding — feature vector for similarity search
-iex> Image.Classification.embed(puppy)
-#Nx.Tensor<f32[768]>
-
-# Promptable segmentation — mask the object at the centre
-iex> %{mask: mask} = Image.Segmentation.segment(puppy)
-iex> cutout = Image.Segmentation.apply_mask!(puppy, mask)
+# Detection — where are the objects and what are they?
+iex> street = Image.open!("street.jpg")
+iex> detections = Image.Detection.detect(street)
+iex> hd(detections)
+%{label: "person", score: 0.94, box: {120, 45, 60, 180}}
 
-# Promptable segmentation — mask the object at a specific point
-iex> %{mask: mask} = Image.Segmentation.segment(puppy, prompt: {:point, 320, 240})
+# Draw bounding boxes on the image
+iex> Image.Detection.draw_bbox_with_labels(detections, street)
 
-# Class-labeled segmentation — every region
-iex> street = Image.open!("street.jpg")
+# Segmentation — which pixels belong to which object?
 iex> segments = Image.Segmentation.segment_panoptic(street)
 iex> Enum.map(segments, & &1.label)
 ["person", "car", "road", "sky"]
 
-# Overlay coloured segments on the original image
-iex> overlay = Image.Segmentation.compose_overlay(street, segments)
+# Colour-coded overlay of all segments
+iex> Image.Segmentation.compose_overlay(street, segments)
 
-# Object detection — bounding boxes with labels
-iex> detections = Image.Detection.detect(street)
-iex> hd(detections)
-%{label: "person", score: 0.94, box: {120, 45, 60, 180}}
+# Promptable segmentation — isolate the object at a specific point
+iex> %{mask: mask} = Image.Segmentation.segment(puppy, prompt: {:point, 320, 240})
+iex> {:ok, cutout} = Image.Segmentation.apply_mask(puppy, mask)
 
-# Draw bounding boxes on the image
-iex> annotated = Image.Detection.draw_bbox_with_labels(detections, street)
+# Embedding — 768-dim feature vector for similarity search
+iex> Image.Classification.embed(puppy)
+#Nx.Tensor<f32[768]>
+```
+
+## Installation
+
+Add `:image_vision` to `mix.exs` along with whichever optional ML backends you need:
+
+```elixir
+def deps do
+  [
+    {:image_vision, "~> 0.2"},
+
+    # Required for Image.Classification and Image.Classification.embed/2
+    {:bumblebee, "~> 0.6"},
+    {:nx, "~> 0.11"},
+    {:exla, "~> 0.9"},      # or {:torchx, "~> 0.9"} for Torch backend
+
+    # Required for Image.Detection and Image.Segmentation
+    {:ortex, "~> 0.1"}
+  ]
+end
 ```
 
+All ML deps are optional — omit any you do not use. The library compiles cleanly without them.
+
 ## Default models
 
-All defaults are permissively licensed (Apache 2.0 / MIT). Models are downloaded automatically on first call and cached to disk — no manual setup needed.
+All models are permissively licensed. Weights are downloaded automatically on first call and cached on disk — no manual setup required.
 
 | Task | Model | License | Size |
 |---|---|---|---|
-| Classification | `facebook/convnext-tiny-224` | Apache 2.0 | ~110 MB |
-| Embedding | `facebook/dinov2-base` | Apache 2.0 | ~340 MB |
-| Promptable segmentation | `SharpAI/sam2-hiera-tiny-onnx` (SAM 2) | Apache 2.0 | ~150 MB |
-| Class-labeled segmentation | `Xenova/detr-resnet-50-panoptic` | Apache 2.0 | ~175 MB |
-| Object detection | `onnx-community/rtdetr_r50vd` (RT-DETR) | Apache 2.0 | ~175 MB |
+| Classification | [`facebook/convnext-tiny-224`](https://huggingface.co/facebook/convnext-tiny-224) | Apache 2.0 | ~110 MB |
+| Embedding | [`facebook/dinov2-base`](https://huggingface.co/facebook/dinov2-base) | Apache 2.0 | ~340 MB |
+| Object detection | [`onnx-community/rtdetr_r50vd`](https://huggingface.co/onnx-community/rtdetr_r50vd) | Apache 2.0 | ~175 MB |
+| Promptable segmentation | [`SharpAI/sam2-hiera-tiny-onnx`](https://huggingface.co/SharpAI/sam2-hiera-tiny-onnx) | Apache 2.0 | ~150 MB |
+| Panoptic segmentation | [`Xenova/detr-resnet-50-panoptic`](https://huggingface.co/Xenova/detr-resnet-50-panoptic) | Apache 2.0 | ~175 MB |
 
 ## Configuration
 
 ### Model cache
 
-ONNX models are cached in a per-user directory by default. Override in `config/runtime.exs`:
+ONNX model weights are cached in a per-user directory by default (`~/.cache/image_vision` on Linux, `~/Library/Caches/image_vision` on macOS). Override in `config/runtime.exs`:
 
 ```elixir
 config :image_vision, :cache_dir, "/var/lib/my_app/models"
 ```
 
-The default is `~/Library/Caches/image_vision` on macOS and `~/.cache/image_vision` on Linux.
-
 ### Classification serving
 
-`Image.Classification` runs a supervised Bumblebee serving. It autostarts by default:
+`Image.Classification` runs a supervised [Bumblebee](https://hex.pm/packages/bumblebee) serving. It does not autostart by default. Start it in your application's supervision tree:
+
+```elixir
+# application.ex
+def start(_type, _args) do
+  children = [
+    Image.Classification.classifier(),
+    Image.Classification.embedder()   # omit if you do not need embeddings
+  ]
+
+  Supervisor.start_link(children, strategy: :one_for_one)
+end
+```
+
+Or enable autostart via config so `ImageVision.Supervisor` handles it:
 
 ```elixir
 # config/runtime.exs
-config :image_vision, :classifier,
-  model: {:hf, "facebook/convnext-large-224-22k-1k"},  # larger model
-  featurizer: {:hf, "facebook/convnext-large-224-22k-1k"},
-  autostart: true
+config :image_vision, :classifier, autostart: true
 ```
 
-Set `autostart: false` to manage the serving in your own supervision tree:
+To use a different model:
 
 ```elixir
-# application.ex
-children = [
-  Image.Classification.classifier(),
-  Image.Classification.embedder()
-]
+config :image_vision, :classifier,
+  model: {:hf, "facebook/convnext-large-224-22k-1k"},
+  featurizer: {:hf, "facebook/convnext-large-224-22k-1k"},
+  autostart: true
 ```
 
 ## Guides
 
 - [Classification](https://github.com/elixir-image/image_vision/blob/v0.2.0/guides/classification.md) — classifying images and computing embeddings
-- [Segmentation](https://github.com/elixir-image/image_vision/blob/v0.2.0/guides/segmentation.md) — promptable and class-labeled segmentation
 - [Detection](https://github.com/elixir-image/image_vision/blob/v0.2.0/guides/detection.md) — bounding-box object detection
-
-## Design
-
-`ImageVision` is for developers who want answers, not ML configuration. The defaults are chosen for permissive licensing, broad applicability, and reasonable size — not raw benchmark ranking. Power users can override every default via options; most users never need to.
-
-See [CLAUDE.md](https://github.com/elixir-image/image_vision/blob/v0.2.0/CLAUDE.md) for the full design rationale.
+- [Segmentation](https://github.com/elixir-image/image_vision/blob/v0.2.0/guides/segmentation.md) — promptable and panoptic segmentation

lib/detection.ex

@@ -9,12 +9,12 @@ if ImageVision.ortex_configured?() do
 
     ## Quick start
 
-        iex> street = Image.open!("./test/support/images/street.jpg")
-        iex> [%{label: _, score: _, box: _} | _] = Image.Detection.detect(street)
+        iex> car = Image.open!("./test/support/images/lamborghini-forsennato-concept.jpg")
+        iex> [%{label: _, score: _, box: _} | _] = Image.Detection.detect(car)
 
     ## Default model
 
-    The default is [RT-DETR](https://huggingface.co/PekingU/rtdetr_r50vd) —
+    The default is [RT-DETR](https://huggingface.co/onnx-community/rtdetr_r50vd) —
     a real-time, transformer-based detector that beats YOLOv8 on
     COCO and is **Apache 2.0 licensed** (unlike YOLOv8/11 which are
     AGPL). The ONNX export is hosted at
@@ -117,9 +117,9 @@ if ImageVision.ortex_configured?() do
 
     ### Examples
 
-        iex> street = Image.open!("./test/support/images/street.jpg")
+        iex> car = Image.open!("./test/support/images/lamborghini-forsennato-concept.jpg")
         iex> [%{label: _, score: _, box: _} | _] =
-        ...>   Image.Detection.detect(street, min_score: 0.5)
+        ...>   Image.Detection.detect(car, min_score: 0.5)
 
     """
     @spec detect(image :: Vimage.t(), options :: Keyword.t()) :: [detection()]
@@ -144,58 +144,77 @@ if ImageVision.ortex_configured?() do
     @doc """
     Draws bounding boxes with class labels onto an image.
 
+    Builds an SVG overlay — one box and label per detection — and
+    composites it onto the image. Each distinct class label gets a
+    consistent colour so multiple detections of the same class are
+    easy to identify at a glance.
+
     ### Arguments
 
     * `detections` is the list returned from `detect/2`.
 
     * `image` is the image upon which detection was run.
 
-    ### Options
-
-    * `:stroke_color` is the box outline color. The default is `:red`.
-
-    * `:stroke_width` is the box outline thickness in pixels. The
-      default is `4`.
-
-    * `:font_size` is the label font size. The default is `20`.
+    * `options` is a keyword list of options. Currently unused;
+      accepted for forward compatibility.
 
     ### Returns
 
     * The annotated `t:Vix.Vips.Image.t/0`.
 
     ### Examples
 
-        iex> street = Image.open!("./test/support/images/street.jpg")
+        iex> car = Image.open!("./test/support/images/lamborghini-forsennato-concept.jpg")
         iex> annotated =
-        ...>   street
+        ...>   car
         ...>   |> Image.Detection.detect()
-        ...>   |> Image.Detection.draw_bbox_with_labels(street)
+        ...>   |> Image.Detection.draw_bbox_with_labels(car)
         iex> match?(%Vix.Vips.Image{}, annotated)
         true
 
     """
     @spec draw_bbox_with_labels([detection()], Vimage.t(), Keyword.t()) :: Vimage.t()
-    def draw_bbox_with_labels(detections, %Vimage{} = image, options \\ []) do
-      stroke_color = Keyword.get(options, :stroke_color, :red)
-      stroke_width = Keyword.get(options, :stroke_width, 4)
-      font_size = Keyword.get(options, :font_size, 20)
-
-      {width, height, _bands} = Image.shape(image)
-
-      Enum.reduce(detections, image, fn %{label: label, box: {x, y, w, h}}, acc ->
-        {:ok, box_image} =
-          Image.Shape.rect(w, h, stroke_color: stroke_color, stroke_width: stroke_width)
-
-        {:ok, text_image} =
-          Image.Text.text(label, text_fill_color: stroke_color, font_size: font_size)
-
-        acc
-        |> Image.compose!(box_image, x: x, y: y)
-        |> Image.compose!(text_image,
-          x: min(max(x, 0), width) + 5,
-          y: min(max(y, 0), height) + 5
-        )
-      end)
+    def draw_bbox_with_labels(detections, %Vimage{} = image, _options \\ []) do
+      width = Image.width(image)
+      height = Image.height(image)
+
+      palette = ~w(
+        #e6194b #3cb44b #4363d8 #f58231 #911eb4
+        #42d4f4 #f032e6 #bfef45 #469990 #9a6324
+      )
+
+      label_colors =
+        detections
+        |> Enum.map(& &1.label)
+        |> Enum.uniq()
+        |> Enum.zip(Stream.cycle(palette))
+        |> Map.new()
+
+      boxes_svg =
+        Enum.map(detections, fn %{label: label, score: score, box: {x, y, w, h}} ->
+          color = Map.fetch!(label_colors, label)
+          text = "#{label} #{Float.round(score * 100, 1)}%"
+          label_y = max(0, y - 20)
+          label_w = String.length(text) * 8 + 8
+
+          """
+          <rect x="#{x}" y="#{y}" width="#{w}" height="#{h}"
+                fill="none" stroke="#{color}" stroke-width="2"/>
+          <rect x="#{x}" y="#{label_y}" width="#{label_w}" height="20" fill="#{color}"/>
+          <text x="#{x + 4}" y="#{label_y + 14}"
+                font-family="sans-serif" font-size="13" font-weight="bold" fill="white">#{text}</text>
+          """
+        end)
+        |> Enum.join()
+
+      svg = """
+      <svg xmlns="http://www.w3.org/2000/svg" width="#{width}" height="#{height}">
+        #{boxes_svg}
+      </svg>
+      """
+
+      {:ok, overlay} = Image.open(svg, access: :sequential)
+      Image.compose!(image, overlay)
     end
 
     @doc """

lib/segmentation.ex

@@ -245,7 +245,7 @@ if ImageVision.ortex_configured?() do
 
     ### Examples
 
-        iex> image = Image.open!("./test/support/images/street.jpg")
+        iex> image = Image.open!("./test/support/images/puppy.webp")
         iex> segments = Image.Segmentation.segment_panoptic(image)
         iex> is_list(segments)
         true
@@ -345,7 +345,7 @@ if ImageVision.ortex_configured?() do
 
     ### Examples
 
-        iex> image = Image.open!("./test/support/images/street.jpg")
+        iex> image = Image.open!("./test/support/images/puppy.webp")
         iex> segments = Image.Segmentation.segment_panoptic(image)
         iex> overlay = Image.Segmentation.compose_overlay(image, segments)
         iex> match?(%Vix.Vips.Image{}, overlay)