Image#region: a region as a new image, the image unchanged

Like crop on a clone, without copying the whole image first (it was
done as new Image(w, h).composite(source, -x, -y)). Clipped like crop,
whose bounds it shares; on a frame it gives a plain image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BsU2GDnECphmYTjLB5UeZv

Author: matmen

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## 3.7.1
 
+### Features
+
+- `Image#region(x, y, width, height)` copies a region into a new image and leaves the image as it is (like `crop`
+  on a clone, without copying the whole image). It's clipped like `crop`; on a frame it gives a plain image.
+
 ### Improvements
 
 - Optimized lossy WebP animations are smaller: like libwebp's, they leave out pixels that changed by up to a tolerance

README.md

@@ -51,6 +51,7 @@ deno add jsr:@matmen/imagescript     # Deno (npm:imagescript works too)
   fonts and color emoji)
 - [Resizing](https://imagescript.matmen.dev/classes/Image.html#resize) (bilinear, bicubic, area averaging and nearest neighbor)
 - Image manipulation functions ([crop](https://imagescript.matmen.dev/classes/Image.html#crop)
+  , [region](https://imagescript.matmen.dev/classes/Image.html#region)
   , [rotate](https://imagescript.matmen.dev/classes/Image.html#rotate)
   , [cropCircle](https://imagescript.matmen.dev/classes/Image.html#cropcircle)
   , [roundCorners](https://imagescript.matmen.dev/classes/Image.html#roundcorners)

src/image.ts

@@ -884,6 +884,28 @@ export class Image {
      * @param height The new images height
      */
     crop(x: number, y: number, width: number, height: number): this {
+        return this.__apply__(this.__crop__(...this.__crop_bounds__(x, y, width, height)));
+    }
+
+    /**
+     * Copies a region of the image into a new image, this one stays unchanged (like {@link Image.crop} on a clone,
+     * without copying the whole image). The region is clipped to the image, so the result can be smaller than the
+     * requested size
+     * @param x The x offset (0-based)
+     * @param y The y offset (0-based)
+     * @param width The region's width
+     * @param height The region's height
+     */
+    region(x: number, y: number, width: number, height: number): Image {
+        return this.__crop__(...this.__crop_bounds__(x, y, width, height));
+    }
+
+    /**
+     * A crop region clipped to the image as [x, y, width, height]
+     * @internal
+     * @ignore
+     */
+    protected __crop_bounds__(x: number, y: number, width: number, height: number): [number, number, number, number] {
         x = ~~finite(x, 'x');
         y = ~~finite(y, 'y');
         width = ~~finite(width, 'width');
@@ -894,7 +916,7 @@ export class Image {
         if (right <= left || bottom <= top)
             throw new RangeError('Crop region does not overlap the image');
 
-        return this.__apply__(this.__crop__(left, top, right - left, bottom - top));
+        return [left, top, right - left, bottom - top];
     }
 
     /**

tests/crop.js

@@ -1,5 +1,5 @@
 const fs = require('fs').promises;
-const {Image} = require('..');
+const {Image, Frame} = require('..');
 const samePixels = require('./util/pixels');
 
 (async () => {
@@ -14,4 +14,29 @@ const samePixels = require('./util/pixels');
 
     const target = await fs.readFile('./tests/targets/crop.png');
     if (!await samePixels(target, encoded)) process.exit(1);
+
+    // region: the same pixels as a new image, the source unchanged; clipped like crop
+    const panic = message => {
+        console.error(message);
+        process.exit(1);
+    };
+    const source = new Image(512, 512).fill((x, y) => Image.hslToColor((x + y) / 1024, 1, .5));
+    const before = Buffer.from(source.bitmap);
+    const region = source.region(128, 128, 128, 128);
+    if (!await samePixels(target, await region.encode(1, {creationTime: 0, software: ''}))) panic('region: wrong pixels');
+    if (!Buffer.from(source.bitmap).equals(before)) panic('region: changed the source');
+    region.fill(0);
+    if (!Buffer.from(source.bitmap).equals(before)) panic('region: shares memory with the source');
+
+    const clipped = source.region(-10, 500, 30, 30);
+    if (clipped.width !== 20 || clipped.height !== 12) panic(`region: clipped to ${clipped.width}x${clipped.height} instead of 20x12`);
+    if (clipped.getPixelAt(1, 1) !== source.getPixelAt(1, 501)) panic('region: clipped region has wrong pixels');
+    let threw = false;
+    try { source.region(600, 0, 10, 10); } catch (err) { threw = err instanceof RangeError; }
+    if (!threw) panic('region: a region outside the image should throw a RangeError');
+
+    // a frame's region is a plain image, the frame stays as it is
+    const frame = Frame.from(source, {duration: 100, xOffset: 4, yOffset: 6});
+    const part = frame.region(0, 0, 10, 10);
+    if (part instanceof Frame || part.width !== 10 || frame.width !== 512 || frame.xOffset !== 4) panic('region: frames');
 })();