Vision
Hooks for image captioning, object detection, classification, and segmentation.
Vision Hooks
See it in action
Try the Vision block and Image Studio block for working demos of these hooks.
useCaptionImage
Generate a text caption for an image.
import { useCaptionImage } from '@localmode/react';
import { transformers } from '@localmode/transformers';
const model = transformers.imageCaptioner('Xenova/vit-gpt2-image-captioning');
function Demo() {
const { data, isLoading, execute } = useCaptionImage({ model });
// execute(imageDataUrl) => data.caption = "A cat sitting on a couch"
}useDetectObjects
Detect objects with bounding boxes.
import { useDetectObjects } from '@localmode/react';
const { data, execute } = useDetectObjects({ model });
await execute(imageDataUrl);
// data.objects = [{ label: 'person', score: 0.95, box: { x, y, width, height } }]useClassifyImage
Classify an image into categories.
import { useClassifyImage } from '@localmode/react';
const { data, execute } = useClassifyImage({ model });
await execute(imageDataUrl);
// data.label = 'cat', data.score = 0.97useSegmentImage
Segment an image into regions with masks.
import { useSegmentImage } from '@localmode/react';
const { data, execute } = useSegmentImage({ model });
await execute(imageDataUrl);
// data.masks = [{ label: 'background', mask: Uint8Array, score: 0.98 }]useClassifyImageZeroShot
Zero-shot image classification with custom labels (no fine-tuning needed).
import { useClassifyImageZeroShot } from '@localmode/react';
const { data, execute } = useClassifyImageZeroShot({ model });
await execute({ image: imageDataUrl, labels: ['cat', 'dog', 'bird'] });
// data.label = 'cat', data.score = 0.92useExtractImageFeatures
Extract feature vectors from images for similarity comparison.
import { useExtractImageFeatures } from '@localmode/react';
const { data, execute } = useExtractImageFeatures({ model });
await execute(imageDataUrl);
// data.features = Float32Array(768)useImageToImage
Image super-resolution or style transfer.
import { useImageToImage } from '@localmode/react';
const { data, execute } = useImageToImage({ model });
await execute(imageDataUrl);
// data.image = 'data:image/png;base64,...' (upscaled/transformed image)All vision hooks accept image data URLs (from FileReader.readAsDataURL). For model recommendations, see the Transformers guide.
Landmark & Gesture Hooks
@localmode/react provides hooks for MediaPipe landmark and gesture detection.
Each takes { model } (from @localmode/mediapipe) and returns the standard
{ data, error, isLoading, execute, cancel, reset } shape.
import { useDetectHands } from '@localmode/react';
import { mediapipe } from '@localmode/mediapipe';
const { data, execute } = useDetectHands({ model: mediapipe.handLandmarker() });
await execute(imageBlob);
// data.hands = [{ landmarks, worldLandmarks, handedness, score }, ...]| Hook | Detects |
|---|---|
useDetectHands | 21-point hand landmarks |
useDetectPose | 33-point body pose landmarks |
useDetectFace | Face bounding boxes and keypoints |
useDetectFaceLandmarks | 478-point face mesh (+ optional blendshapes) |
useRecognizeGesture | Hand gestures (8 categories) |
For real-time 30-60fps video tracking, use useStreamingTracker with the streaming tracker API from
@localmode/mediapipe instead of these single-frame hooks.
useStreamingTracker (Experimental)
Owns the start/stop lifecycle of a real-time video tracker (the @localmode/mediapipe createHand/Pose/Face/GestureTracker factories). The trackers run their own frame loop internally — the hook injects a results sink at creation, mirrors the latest results into React state, measures fps over a one-second sliding window, and guarantees close() on unmount. The tracker is created lazily on the first start() and reused across start/stop cycles (the model stays loaded).
Experimental
useStreamingTracker is experimental and its API may change in a future minor release.
import { useRef } from 'react';
import { useStreamingTracker } from '@localmode/react';
import { createHandTracker } from '@localmode/mediapipe';
import type { HandLandmarkResultItem } from '@localmode/core';
function HandOverlay() {
const videoRef = useRef<HTMLVideoElement>(null);
const { status, results, fps, error, start, stop } = useStreamingTracker<
HandLandmarkResultItem[]
>({
video: videoRef,
create: ({ video, onResults, onError }) =>
createHandTracker({ video, onResults, onError }),
});
return (
<>
<video ref={videoRef} autoPlay muted playsInline />
<button onClick={status === 'running' ? stop : start}>
{status === 'running' ? `Stop (${fps} fps)` : 'Start'}
</button>
{results?.map((hand, i) => <HandSkeleton key={i} hand={hand} />)}
</>
);
}Options
| Option | Type | Description |
|---|---|---|
create | (context) => StreamingTrackerLike | Promise<StreamingTrackerLike> | Factory creating the tracker. Receives { video, onResults, onError } — wire these into the tracker's creation options |
video | RefObject<HTMLVideoElement | null> | (() => HTMLVideoElement | null) | The video element to track — a ref object or a getter |
onResults | (results, timestampMs) => void | Called once per processed frame with the latest results |
autoStart | boolean | Start tracking on mount (default: false) |
Return Value
| Property | Type | Description |
|---|---|---|
status | 'idle' | 'starting' | 'running' | 'error' | Lifecycle status. Per-frame errors set error without leaving 'running' |
results | TResults | null | Latest per-frame results (null before the first frame) |
fps | number | Processed frames per second over the last second (0 when stopped) |
error | Error | null | Latest startup or per-frame error |
start | () => Promise<void> | Create (if needed) and start the tracker |
stop | () => void | Pause tracking; the tracker (and its model) stays alive for restart |
Blocks
| App | Description | Links |
|---|---|---|
| Vision (Object Detector) | Detect objects with useDetectObjects | Live block · Source |
| Image Studio (Background Remover) | Segment images with useSegmentImage | Live block · Source |
| Image Studio (Photo Enhancer) | Enhance images with useImageToImage | Live block · Source |
| Image Studio (Image Captioner) | Caption images with useOperationList | Live block · Source |
| Vision (Live Tracker) | Real-time hand/pose/face/gesture tracking | Live block · Source |
| Photo Search (Duplicate Finder) | Compare image features with useSequentialBatch | Live block · Source |