Image Manipulator

Crop, resize, rotate, and encode local images on iOS and Android

One.ImageManipulator.transform reads a local file:// image and writes a new JPEG or PNG file in the app’s cache. It never changes the source. The operation runs off the JavaScript thread and needs no photo permission.

import { One } from 'one'

const edited = await One.ImageManipulator.transform(photoUri, {
  crop: { x: 20, y: 20, width: 400, height: 300 },
  resize: { width: 200 },
  rotate: 90,
  format: 'jpeg',
  quality: 0.8,
})
// edited: { uri: 'file:///.../OneImageManipulator/<id>.jpg', width: 150,
//           height: 200, size: <bytes> }

Operations run in this order: crop, resize, then rotate. Crop coordinates are whole pixels from the top left of the upright source image. Resize accepts a width, a height, or both; one dimension preserves the aspect ratio, and both dimensions use exactly the requested size. Rotation is clockwise and accepts 0, 90, 180, or 270 degrees. The default format is JPEG at quality 0.9; quality ranges from 0 to 1 and applies only to JPEG. PNG preserves transparency and takes no quality option. JPEG removes transparency. The result’s size is the encoded file length in bytes.

Use One.FileSystem.delete(result.uri) when the cached result is no longer needed. To keep it, move it into the app’s documents directory. To add it to Photos, pass its URI to One.PhotoLibrary.saveImage after requesting add-only permission. Network URLs need to be downloaded to a local file first.

The promise rejects with error.code E_IMAGE_URI for a non-file URI, E_IMAGE_FILE for a missing file, E_IMAGE_DECODE for an unsupported image, E_IMAGE_INPUT for invalid crop, resize, rotation, quality, or output size, E_IMAGE_ENCODE for an encoder failure, and E_IMAGE_FAILED for a file write failure. Output is limited to 25 megapixels and 10,000 pixels per side. This API is implemented on iOS and Android. On web, transform() uses canvas and accepts browser image URLs, including data and blob URLs and remote images that permit cross-origin canvas access. The browser decoder applies EXIF orientation, including mirrored orientations. The same crop, resize, clockwise rotation, output limits, format, and quality rules apply. Rendering runs on the browser thread. The result is a blob URL accepted by One.UI.Image, HTML images, and fetch; release it with URL.revokeObjectURL(result.uri) when no longer needed. SSR rejects with ImageManipulator.transform needs an iOS or Android build. Browser decoding and canvas failures reject with browser errors.