LocalMode
React

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.97

useSegmentImage

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.92

useExtractImageFeatures

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 }, ...]
HookDetects
useDetectHands21-point hand landmarks
useDetectPose33-point body pose landmarks
useDetectFaceFace bounding boxes and keypoints
useDetectFaceLandmarks478-point face mesh (+ optional blendshapes)
useRecognizeGestureHand 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

OptionTypeDescription
create(context) => StreamingTrackerLike | Promise<StreamingTrackerLike>Factory creating the tracker. Receives { video, onResults, onError } — wire these into the tracker's creation options
videoRefObject<HTMLVideoElement | null> | (() => HTMLVideoElement | null)The video element to track — a ref object or a getter
onResults(results, timestampMs) => voidCalled once per processed frame with the latest results
autoStartbooleanStart tracking on mount (default: false)

Return Value

PropertyTypeDescription
status'idle' | 'starting' | 'running' | 'error'Lifecycle status. Per-frame errors set error without leaving 'running'
resultsTResults | nullLatest per-frame results (null before the first frame)
fpsnumberProcessed frames per second over the last second (0 when stopped)
errorError | nullLatest startup or per-frame error
start() => Promise<void>Create (if needed) and start the tracker
stop() => voidPause tracking; the tracker (and its model) stays alive for restart

Blocks

AppDescriptionLinks
Vision (Object Detector)Detect objects with useDetectObjectsLive block · Source
Image Studio (Background Remover)Segment images with useSegmentImageLive block · Source
Image Studio (Photo Enhancer)Enhance images with useImageToImageLive block · Source
Image Studio (Image Captioner)Caption images with useOperationListLive block · Source
Vision (Live Tracker)Real-time hand/pose/face/gesture trackingLive block · Source
Photo Search (Duplicate Finder)Compare image features with useSequentialBatchLive block · Source

On this page