react-native-image-editor-skia 0.1.0

package/src/types.ts

@@ -0,0 +1,203 @@
+/**
+ * Public + internal types for the Skia image editor.
+ *
+ * COORDINATE-SPACE CONTRACT (read this first):
+ * Every annotation's geometry is stored in **image space** — the base image's
+ * full-resolution pixel coordinate system (0..imageWidth, 0..imageHeight).
+ * It is NEVER stored in screen space. A single `imageToScreen` affine matrix
+ * maps image space onto the on-screen canvas; its inverse maps touches back.
+ * Because of this, export can render the exact same numbers off-screen at native
+ * resolution with no rescaling. See `utils/math.ts`.
+ */
+
+export interface Vec2 {
+  x: number;
+  y: number;
+}
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export type ToolType =
+  | 'select'
+  | 'circle'
+  | 'arrow'
+  | 'marker'
+  | 'freehand'
+  | 'text'
+  | 'crop';
+
+export type AnnotationType = 'circle' | 'arrow' | 'marker' | 'freehand' | 'text';
+
+/**
+ * Colors are stored as CSS-style strings ("#RRGGBB" / "#RRGGBBAA" / named).
+ * Skia accepts these directly, and they are trivially serializable for history.
+ */
+export type ColorString = string;
+
+interface BaseAnnotation {
+  id: string;
+  type: AnnotationType;
+  /** Rotation in radians about the annotation's own center. */
+  rotation: number;
+  /** Paint order; higher = drawn on top / hit-tested first. */
+  z: number;
+}
+
+export interface CircleAnnotation extends BaseAnnotation {
+  type: 'circle';
+  center: Vec2;
+  radius: number;
+  strokeColor: ColorString;
+  strokeWidth: number;
+  /** Optional fill; undefined = outline only. */
+  fill?: ColorString;
+}
+
+export interface ArrowAnnotation extends BaseAnnotation {
+  type: 'arrow';
+  start: Vec2;
+  end: Vec2;
+  /** Length of the arrowhead barbs, in image pixels. */
+  headSize: number;
+  strokeColor: ColorString;
+  strokeWidth: number;
+}
+
+export interface MarkerAnnotation extends BaseAnnotation {
+  type: 'marker';
+  /** Highlight rectangle, in image space. */
+  rect: Rect;
+  color: ColorString;
+  /** 0..1 — highlighters are semi-transparent. */
+  opacity: number;
+}
+
+export interface FreehandAnnotation extends BaseAnnotation {
+  type: 'freehand';
+  points: Vec2[];
+  strokeColor: ColorString;
+  strokeWidth: number;
+}
+
+export interface TextAnnotation extends BaseAnnotation {
+  type: 'text';
+  /** Top-left origin of the text box, in image space. */
+  origin: Vec2;
+  text: string;
+  color: ColorString;
+  fontSize: number;
+  /** Wrap width of the text box, in image pixels. */
+  width: number;
+}
+
+export type Annotation =
+  | CircleAnnotation
+  | ArrowAnnotation
+  | MarkerAnnotation
+  | FreehandAnnotation
+  | TextAnnotation;
+
+/**
+ * Non-destructive image transforms. Nothing is baked into pixels until export,
+ * so all of these are undoable.
+ */
+export interface SceneTransform {
+  /** Free-angle rotation of the whole image + its annotations, in radians. */
+  rotation: number;
+  /** Uniform resize factor applied at export. */
+  scale: number;
+  /** Crop region in image space, or null for the full image. */
+  cropRect: Rect | null;
+}
+
+export const IDENTITY_SCENE: SceneTransform = {
+  rotation: 0,
+  scale: 1,
+  cropRect: null,
+};
+
+/** The serializable editor document — everything undo/redo tracks. */
+export interface EditorDocument {
+  annotations: Annotation[];
+  scene: SceneTransform;
+}
+
+export type OutputFormat = 'png' | 'jpeg';
+
+/**
+ * Callback that persists an encoded image to disk. The library has no
+ * filesystem access of its own, so the consumer supplies this using whatever fs
+ * module they already have (react-native-fs, expo-file-system, etc.). It
+ * receives the destination path and the RAW base64 payload (no data-URI prefix).
+ */
+export type WriteFileFn = (path: string, base64: string) => Promise<void>;
+
+export interface ExportOptions {
+  format?: OutputFormat;
+  /** JPEG quality 0..100 (ignored for PNG). Default 100. */
+  quality?: number;
+  /**
+   * Clamp the longest output edge to this many pixels (keeps aspect ratio).
+   * Guards against OOM when snapshotting very large images. Default: no clamp.
+   */
+  maxExportSize?: number;
+  /**
+   * `'base64'` (default) resolves to a base64 string. `'file'` writes the image
+   * to `filePath` using `writeFile` and resolves to that path.
+   */
+  output?: 'base64' | 'file';
+  /** Destination path/URI when `output: 'file'`. */
+  filePath?: string;
+  /** Required when `output: 'file'` — writes the base64 payload to disk. */
+  writeFile?: WriteFileFn;
+  /**
+   * For `output: 'base64'` only. When true (default), returns a
+   * `data:image/...;base64,...` URI. When false, returns raw base64 (no prefix).
+   */
+  dataUri?: boolean;
+}
+
+/** Imperative handle exposed via `ref`. */
+export interface ImageEditorRef {
+  /**
+   * Render the current scene off-screen at full resolution. Resolves to base64
+   * (default) or, with `output: 'file'`, to the written file path.
+   */
+  export: (options?: ExportOptions) => Promise<string>;
+  undo: () => void;
+  redo: () => void;
+  canUndo: () => boolean;
+  canRedo: () => boolean;
+  /** Remove all annotations and reset scene transforms (keeps the base image). */
+  reset: () => void;
+}
+
+/** Source image: a base64 string (raw or data-URI) or a file/remote URI. */
+export type ImageSource =
+  | { base64: string }
+  | { uri: string };
+
+export interface ImageEditorProps {
+  /** Base image to edit. */
+  source: ImageSource;
+  /** Fired when the user taps the built-in export/done control. */
+  onExport?: (base64: string) => void;
+  /** Default export options for the built-in export control. */
+  exportOptions?: ExportOptions;
+  /** Initial stroke color for new shapes. Default "#FF3B30". */
+  initialStrokeColor?: ColorString;
+  /** Initial text color. Default "#FFFFFF". */
+  initialTextColor?: ColorString;
+  /** Palette shown in the color picker. */
+  palette?: ColorString[];
+  /** Hide the built-in toolbar (drive tools yourself via ref/context). */
+  hideToolbar?: boolean;
+  /** Called whenever the loaded image fails to decode. */
+  onError?: (error: Error) => void;
+  style?: import('react-native').StyleProp<import('react-native').ViewStyle>;
+}

package/src/utils/color.ts

@@ -0,0 +1,34 @@
+import type { ColorString } from '../types';
+
+/**
+ * Apply an opacity (0..1) to a hex color string, returning an 8-digit hex
+ * ("#RRGGBBAA"). Used by the marker/highlighter which draws semi-transparently.
+ * Non-hex inputs (named colors, rgba(...)) are returned unchanged.
+ */
+export function withOpacity(color: ColorString, opacity: number): ColorString {
+  const clamped = Math.max(0, Math.min(1, opacity));
+  const hex = color.trim();
+  if (!hex.startsWith('#')) {
+    return hex;
+  }
+  let r: string;
+  let g: string;
+  let b: string;
+  if (hex.length === 4) {
+    // #RGB
+    r = hex[1]! + hex[1]!;
+    g = hex[2]! + hex[2]!;
+    b = hex[3]! + hex[3]!;
+  } else if (hex.length === 7 || hex.length === 9) {
+    // #RRGGBB or #RRGGBBAA (ignore existing alpha)
+    r = hex.slice(1, 3);
+    g = hex.slice(3, 5);
+    b = hex.slice(5, 7);
+  } else {
+    return hex;
+  }
+  const a = Math.round(clamped * 255)
+    .toString(16)
+    .padStart(2, '0');
+  return `#${r}${g}${b}${a}`;
+}

package/src/utils/id.ts

@@ -0,0 +1,7 @@
+let counter = 0;
+
+/** Small unique id generator (JS thread only — avoids a nanoid dependency). */
+export function genId(prefix = 'a'): string {
+  counter += 1;
+  return `${prefix}_${Date.now().toString(36)}_${counter.toString(36)}`;
+}

package/src/utils/math.ts

@@ -0,0 +1,222 @@
+/**
+ * Pure 2D affine-matrix math. Every function is marked `worklet` so it can run
+ * on the UI thread inside gesture handlers as well as on the JS thread.
+ *
+ * A matrix `Mat` maps a point p to p' via:
+ *   x' = a*x + c*y + e
+ *   y' = b*x + d*y + f
+ * (the canonical CSS/canvas affine convention).
+ */
+
+import type { Rect, SceneTransform, Vec2 } from '../types';
+
+export interface Mat {
+  a: number;
+  b: number;
+  c: number;
+  d: number;
+  e: number;
+  f: number;
+}
+
+export function identity(): Mat {
+  'worklet';
+  return { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 };
+}
+
+/** Returns m1 ∘ m2 (applies m2 first, then m1). */
+export function multiply(m1: Mat, m2: Mat): Mat {
+  'worklet';
+  return {
+    a: m1.a * m2.a + m1.c * m2.b,
+    b: m1.b * m2.a + m1.d * m2.b,
+    c: m1.a * m2.c + m1.c * m2.d,
+    d: m1.b * m2.c + m1.d * m2.d,
+    e: m1.a * m2.e + m1.c * m2.f + m1.e,
+    f: m1.b * m2.e + m1.d * m2.f + m1.f,
+  };
+}
+
+export function translation(tx: number, ty: number): Mat {
+  'worklet';
+  return { a: 1, b: 0, c: 0, d: 1, e: tx, f: ty };
+}
+
+export function scaling(sx: number, sy: number): Mat {
+  'worklet';
+  return { a: sx, b: 0, c: 0, d: sy, e: 0, f: 0 };
+}
+
+export function rotation(theta: number): Mat {
+  'worklet';
+  const cos = Math.cos(theta);
+  const sin = Math.sin(theta);
+  return { a: cos, b: sin, c: -sin, d: cos, e: 0, f: 0 };
+}
+
+export function invert(m: Mat): Mat {
+  'worklet';
+  const det = m.a * m.d - m.b * m.c;
+  if (det === 0) {
+    return identity();
+  }
+  const inv = 1 / det;
+  return {
+    a: m.d * inv,
+    b: -m.b * inv,
+    c: -m.c * inv,
+    d: m.a * inv,
+    e: (m.c * m.f - m.d * m.e) * inv,
+    f: (m.b * m.e - m.a * m.f) * inv,
+  };
+}
+
+export function applyToPoint(m: Mat, p: Vec2): Vec2 {
+  'worklet';
+  return {
+    x: m.a * p.x + m.c * p.y + m.e,
+    y: m.b * p.x + m.d * p.y + m.f,
+  };
+}
+
+/** Rotate point `p` by `theta` radians about `center`. */
+export function rotatePoint(p: Vec2, center: Vec2, theta: number): Vec2 {
+  'worklet';
+  const cos = Math.cos(theta);
+  const sin = Math.sin(theta);
+  const dx = p.x - center.x;
+  const dy = p.y - center.y;
+  return {
+    x: center.x + dx * cos - dy * sin,
+    y: center.y + dx * sin + dy * cos,
+  };
+}
+
+export interface Layout {
+  width: number;
+  height: number;
+}
+
+export interface ImageSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * The base fit scale used to "contain" the image inside the on-screen layout,
+ * before any user scene scale is applied.
+ */
+export function fitScale(image: ImageSize, layout: Layout): number {
+  'worklet';
+  if (image.width <= 0 || image.height <= 0) {
+    return 1;
+  }
+  return Math.min(layout.width / image.width, layout.height / image.height);
+}
+
+/**
+ * Compose the image→screen matrix:
+ *   M = T(center) · R(rotation) · S(fit·userScale) · T(-imageCenter)
+ *
+ * The on-screen Skia `<Group>` uses `sceneTransforms2d` (below), built from the
+ * SAME parameters, so the preview and this matrix stay in lock-step. Gestures
+ * use `invert(M)` to map screen touches back into image space.
+ */
+export function imageToScreenMatrix(
+  scene: SceneTransform,
+  image: ImageSize,
+  layout: Layout
+): Mat {
+  'worklet';
+  const s = fitScale(image, layout) * scene.scale;
+  const cx = layout.width / 2;
+  const cy = layout.height / 2;
+  let m = translation(cx, cy);
+  m = multiply(m, rotation(scene.rotation));
+  m = multiply(m, scaling(s, s));
+  m = multiply(m, translation(-image.width / 2, -image.height / 2));
+  return m;
+}
+
+/**
+ * Skia `Transforms2d` array for the on-screen scene `<Group>`. Applied in order,
+ * this reproduces `imageToScreenMatrix` exactly.
+ */
+export function sceneTransforms2d(
+  scene: SceneTransform,
+  image: ImageSize,
+  layout: Layout
+): { translateX: number }[] | object[] {
+  'worklet';
+  const s = fitScale(image, layout) * scene.scale;
+  return [
+    { translateX: layout.width / 2 },
+    { translateY: layout.height / 2 },
+    { rotate: scene.rotation },
+    { scaleX: s },
+    { scaleY: s },
+    { translateX: -image.width / 2 },
+    { translateY: -image.height / 2 },
+  ];
+}
+
+export function clampSizeToMax(
+  width: number,
+  height: number,
+  maxSize?: number
+): { width: number; height: number } {
+  'worklet';
+  if (!maxSize || maxSize <= 0) {
+    return { width, height };
+  }
+  const longest = Math.max(width, height);
+  if (longest <= maxSize) {
+    return { width, height };
+  }
+  const k = maxSize / longest;
+  return { width: Math.round(width * k), height: Math.round(height * k) };
+}
+
+/** Axis-aligned bounding box of a set of points. */
+export function boundsOfPoints(points: Vec2[]): Rect {
+  'worklet';
+  if (points.length === 0) {
+    return { x: 0, y: 0, width: 0, height: 0 };
+  }
+  let minX = points[0]!.x;
+  let minY = points[0]!.y;
+  let maxX = points[0]!.x;
+  let maxY = points[0]!.y;
+  for (let i = 1; i < points.length; i++) {
+    const p = points[i]!;
+    if (p.x < minX) minX = p.x;
+    if (p.y < minY) minY = p.y;
+    if (p.x > maxX) maxX = p.x;
+    if (p.y > maxY) maxY = p.y;
+  }
+  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+
+export function rectCenter(r: Rect): Vec2 {
+  'worklet';
+  return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+}
+
+export function distance(a: Vec2, b: Vec2): number {
+  'worklet';
+  return Math.hypot(a.x - b.x, a.y - b.y);
+}
+
+/** Shortest distance from point `p` to segment `a`→`b`. */
+export function distanceToSegment(p: Vec2, a: Vec2, b: Vec2): number {
+  'worklet';
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  const lenSq = dx * dx + dy * dy;
+  if (lenSq === 0) {
+    return distance(p, a);
+  }
+  let t = ((p.x - a.x) * dx + (p.y - a.y) * dy) / lenSq;
+  t = Math.max(0, Math.min(1, t));
+  return distance(p, { x: a.x + t * dx, y: a.y + t * dy });
+}