Download the PHP package pteal79/image-annotator without Composer

pteal79/image-annotator

A NativePHP Mobile v4 plugin that opens a full-screen, fully native image annotation editor on iOS (Swift, UIKit) and Android (Kotlin, custom View). There is no WebView and no JavaScript.

The user draws freehand lines, straight lines, rectangles and text on an image. Everything stays editable until they save: shapes can be selected, moved, resized, restyled, re-ordered and deleted, with undo and redo for every change. On Save the annotations are flattened into a JPEG (quality 0.92, same pixel size as the input) in the app's cache dir, and the path comes back to Laravel as an event.

The plugin only works on local files. It never touches the network.

Contents

• Requirements
• Installation
• Usage
• Events
• SuperNative example
• The editor
• Behaviour notes
• Testing
• License

Requirements

• PHP 8.4 or later
• NativePHP Mobile v4 (nativephp/mobile ^4.0)
• iOS 18.2 or later, Android 8.0 (API 26) or later
• No permissions. The plugin only reads the paths you give it and writes to the app's cache dir.

Installation

During development, load it from a local folder with a path repository in your app's composer.json:

Register it with NativePHP, then rebuild:

The manifest adds one Android activity (AnnotatorActivity, not exported). Nothing is added to Info.plist.

Usage

• Use named arguments. The PHP signature is open(string $imagePath, string $id, ?string $originalPath = null): bool.
• open() returns straight away. It returns true when the editor is opening, and false off-device or when native refused (a refusal still sends ImageAnnotationFailed).
• A blank imagePath or id throws InvalidArgumentException. A blank originalPath is treated as none.
• Pass images that are ready to use: downscaled to a long edge of at most 4096 px. EXIF orientation is applied when decoding, so the image is drawn and exported upright.

Events

Every open() ends with exactly one of these events. The editor is dismissed before the event is sent.

All three live in Pteal79\ImageAnnotator\Events. Your app owns outputPath once the event arrives: move or upload it, then delete it.

Save failures do not send ImageAnnotationFailed. The editor shows "Couldn't save image" and stays open so the user can try again or close.

SuperNative example

The editor

• Tools: Select (default), Pen (freehand), Line, Rect and Text.
• Colour: red (#ef4444) by default, from a palette of red, orange, yellow, green, blue, black and white.
• Size: S / M / L / XL (default M). Stroke widths 2 / 4 / 8 / 16 pt and font sizes 28 / 44 / 64 / 88 pt, measured on screen, so a Medium line looks the same on a 1000 px and a 4000 px image.
• Rectangles can be filled (fill colour defaults to white).
• Select: tap a shape to select it. Lines have 2 handles and rectangles 8; drag them to resize (a rectangle flips when dragged past its anchor). Drag any shape to move it. Tap text without moving to re-edit it. With a shape selected, colour, size and fill changes restyle it, and the context row shows layer order (to front, forward, backward, to back) and Delete.
• Text: tap to open an inline multi-line field with a format bar (font, bold, italic, underline, size, Done, Cancel). Tapping outside commits. Empty text is not added. The field is kept above the keyboard.
• Zoom: pinch with two fingers to zoom (up to 8x) and drag with two fingers to pan. In Select mode, one finger on empty space also pans while zoomed in. The floating controls at the bottom-right of the canvas zoom out, zoom in, and show the zoom level; tap the level to fit the image again. A second finger never draws: it drops any stroke or drag in progress.
• History: undo, redo and Clear all (confirmed, undoable). Revert (confirmed, not undoable) appears only when originalPath was given.
• Close asks "Discard changes?" when there are unsaved changes. The Android back button behaves the same (while the text field is open, back cancels the text edit first).

Annotations are only held in memory. Nothing but the flattened JPEG is ever saved.

Behaviour notes

Where the spec left room, the plugin does this on both platforms:

• Shape geometry is stored in image pixels. Sizes chosen in screen points (dp on Android) are multiplied by the current image-pixels-per-point scale when a shape is created, so rotating the device never moves shapes.
• The 3 pt move threshold applies to every drag, not only text, so a tap that selects a shape never pushes an undo step.
• The text hit padding (8) is in screen points, like the other touch tolerances, so text is as easy to tap on a large image as on a small one.
• A tap with Pen, Line or Rect that draws nothing visible (fewer than 2 points, zero length or zero size) adds no shape and no undo step.
• Re-editing text without changing its size keeps its exact stored font size.
• The Impact font is not shipped with iOS or Android: iOS uses a heavy condensed system font, Android sans-serif-condensed bold. Georgia uses the platform serif on Android.
• Zoom does not change the size a new shape gets: stroke widths and font sizes are based on the fitted image, so an M line is the same part of the image at any zoom and the size buttons always match. Touch tolerances, handles and the selection outline stay the same size on screen at any zoom, so small shapes are easier to hit when zoomed in. The inline text field shows text at its real on-screen size for the current zoom.
• iOS presents the editor .fullScreen, which has no swipe-to-dismiss gesture. If it is dismissed by anything other than its own buttons, it sends ImageAnnotationCancelled.
• The output background is white, so transparent PNG areas become white in the JPEG.

Testing

The Pest suite covers the facade, the bridge parameters, the event payloads, the manifest and cross-platform consistency checks on the native sources. The native editors need a device or simulator.

License

MIT. See LICENSE.