Download the PHP package zielu92/filament-image-labeler without Composer

Filament Image Labeler

A Filament plugin for annotating images with rectangles and polygons. Built on Annotorious, it provides a canvas-based drawing tool as a Filament form field, plus a polymorphic persistence layer so any Eloquent model can have annotations.

Features

• Draw rectangles and polygons on images
• Stable color assignment per annotation (hash-based, not index-based)
• Polymorphic annotations table — attach annotations to any model
• HasAnnotations trait with syncAnnotations() for easy CRUD
• Flexible metadata JSON column — store whatever your app needs
• Works with private/public file storage
• Filament v5 compatible

Installation

Run the migration (auto-loaded from the package, no publishing needed):

How It Works

The package has two parts:

1. ImageLabel form field — Renders an image with an Annotorious overlay. Users draw shapes on the image. The component emits its state as a JSON array of [{id, target}] objects where id is a unique annotation identifier and target contains the W3C Web Annotation geometry data.

2. Persistence layer — An Annotation Eloquent model and HasAnnotations trait that store annotations in a polymorphic annotations table. Each annotation has an annotation_id (the Annotorious UUID), geometry (JSON), and an optional metadata (JSON) column for any app-specific data.

Database Schema

Usage

1. Add the trait to your model

This gives your model:

• $photo->annotations() — morphMany relationship
• $photo->syncAnnotations(array $data) — create/update/delete in one call
• Automatic cascade delete when the parent model is deleted

2. Add the ImageLabel field to your Filament form

3. Sync annotations on save

The ImageLabel component emits raw geometry data. Your app decides what metadata to attach. Use Filament's page lifecycle hooks to persist:

4. Hydrate annotations on edit

Full Example: Repeater with color swatch

A common pattern is to pair the ImageLabel with a Filament Repeater that shows editable metadata for each annotation. When ->coloredAnnotations() is enabled, you can display a matching color swatch in the repeater:

The hashColor helper (same djb2 algorithm used internally by the package) is available as AnnotationColor::forId($id, $palette).

Each repeater row displays a colored square that matches the annotation's color on the canvas. The color is deterministic — same annotation ID always produces the same color, regardless of order.

When a user deletes a repeater item, the afterStateUpdated callback rebuilds the canvas state from the remaining items, effectively removing the annotation from the image as well.

Tip: If you want annotations to only be removable from the canvas (not the repeater), set ->deletable(false) and rely solely on the "Clear All" button or Annotorious's built-in delete (select + backspace).

The syncAnnotations Method

Behavior:

• Creates annotations that don't exist yet (matched by annotation_id)
• Updates annotations that already exist
• Deletes annotations whose annotation_id is no longer in the array
• Passing [] deletes all annotations for the model

The geometry field accepts either an array or a JSON string (auto-decoded). The metadata field is nullable — pass null or omit it if you don't need custom data.

ImageLabel Configuration

Colored Annotations

By default, annotations use Annotorious's default styling (white/light blue outlines). To enable distinct colors per annotation, pass a color palette:

Each annotation gets a deterministic color based on a hash of its ID. The same annotation always gets the same color regardless of order. Colors cycle through the palette when there are more annotations than colors.

To use the color in your repeater (matching the canvas), use the package's AnnotationColor helper:

Working with Private Files

If your images are stored on a private disk, use temporary signed URLs:

Testing

The package provides the HasAnnotations trait which is easily testable:

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

This package uses Annotorious for the image annotation canvas, licensed under the BSD 3-Clause License.

License

The MIT License (MIT). Please see License File for more information.