pixelati 0.1.0 → 0.1.1

package/README.md

@@ -44,8 +44,10 @@ pixelati <image> [options]
 | Option | Description |
 |---|---|
 | `-w, --width <n>` | Output width in columns. Defaults to the terminal width, or 80 when piped. |
+| `-H, --height <n>` | Maximum height in rows. The image is scaled to fit within width × height, preserving aspect, so tall images stay inside the box. |
 | `-t, --threshold <n>` | Alpha cutoff from 0 to 255. Pixels at or below it are treated as transparent. Default 128. |
 | `-b, --background <hex>` | Composite the image onto this colour instead of leaving transparent gaps (for example `#1e1e2e`). |
+| `-T, --trim` | Crop uniform or transparent borders before scaling, so a subject centred in a large canvas (like a sprite) fills the frame instead of rendering tiny. |
 | `-o, --output <file>` | Write the art to a file instead of printing it. |
 | `-h, --help` | Show help. |
 

package/dist/cli.js

@@ -8,14 +8,17 @@ Usage:
 
 Options:
   -w, --width <n>        Output width in columns (default: terminal width or 80)
+  -H, --height <n>       Max height in rows; scales to fit within width × height
   -t, --threshold <n>    Alpha cutoff 0-255; at or below is transparent (default: 128)
   -b, --background <hex> Composite onto this colour instead of leaving gaps (e.g. #1e1e2e)
   -o, --output <file>    Write the art to a file instead of stdout
+  -T, --trim             Crop uniform/transparent borders so the subject fills the frame
   -h, --help             Show this help
 
 Examples:
   pixelati logo.png
   pixelati photo.jpg -w 60
+  pixelati sprite.png -T -w 24
   pixelati icon.png -b "#000000"
   pixelati banner.png -w 100 -o banner.ans
 `;
@@ -38,6 +41,10 @@ function parseArgs(argv) {
             case "--width":
                 args.width = Number(next());
                 break;
+            case "-H":
+            case "--height":
+                args.height = Number(next());
+                break;
             case "-t":
             case "--threshold":
                 args.threshold = Number(next());
@@ -50,6 +57,10 @@ function parseArgs(argv) {
             case "--output":
                 args.output = next();
                 break;
+            case "-T":
+            case "--trim":
+                args.trim = true;
+                break;
             default:
                 if (a.startsWith("-"))
                     throw new Error(`Unknown option: ${a}`);
@@ -75,8 +86,10 @@ async function main() {
     }
     const opts = {
         width: args.width ?? process.stdout.columns ?? 80,
+        height: args.height,
         threshold: args.threshold,
         background: args.background,
+        trim: args.trim,
     };
     const lines = await renderToLines(args.input, opts);
     if (args.output) {

package/dist/render.d.ts

@@ -1,6 +1,12 @@
 export interface RenderOptions {
     /** Target width in terminal columns (one column per source pixel). */
     width?: number;
+    /**
+     * Maximum height in terminal rows (each row is two pixels tall). When set,
+     * the image is scaled to fit within width × height, preserving aspect, so a
+     * tall image stays inside the box instead of overflowing.
+     */
+    height?: number;
     /** Alpha cutoff (0-255). Pixels at or below this are treated as transparent. */
     threshold?: number;
     /**
@@ -9,6 +15,12 @@ export interface RenderOptions {
      * pixels render as blanks.
      */
     background?: string;
+    /**
+     * Crop uniform/transparent borders before scaling so the subject fills the
+     * frame. Useful for sprites or logos centred in a large transparent canvas,
+     * which would otherwise render tiny and blurry.
+     */
+    trim?: boolean;
 }
 interface RGBA {
     r: number;

package/dist/render.js

@@ -39,18 +39,50 @@ export async function renderToLines(input, opts = {}) {
     const width = Math.max(1, Math.floor(opts.width ?? DEFAULT_WIDTH));
     const threshold = opts.threshold ?? DEFAULT_THRESHOLD;
     const base = opts.background ? parseHex(opts.background) : null;
-    const pipeline = sharp(input);
-    const meta = await pipeline.metadata();
-    if (!meta.width || !meta.height) {
+    // Optionally crop uniform/transparent borders first, so the subject fills the
+    // frame before scaling. trim() can throw on a uniform image; fall back to the
+    // original in that case. Work out the source dimensions after any trim.
+    let source = input;
+    let srcWidth;
+    let srcHeight;
+    if (opts.trim) {
+        try {
+            const t = await sharp(input).trim().toBuffer({ resolveWithObject: true });
+            source = t.data;
+            srcWidth = t.info.width;
+            srcHeight = t.info.height;
+        }
+        catch {
+            const m = await sharp(input).metadata();
+            srcWidth = m.width ?? 0;
+            srcHeight = m.height ?? 0;
+        }
+    }
+    else {
+        const m = await sharp(input).metadata();
+        srcWidth = m.width ?? 0;
+        srcHeight = m.height ?? 0;
+    }
+    if (!srcWidth || !srcHeight) {
         throw new Error("Could not read image dimensions.");
     }
     // Preserve aspect ratio. Each pixel is one column wide and (paired) one text
-    // row holds two pixels, so square pixels keep the picture's proportions.
-    let height = Math.max(2, Math.round(width * (meta.height / meta.width)));
-    if (height % 2 === 1)
-        height += 1; // even rows pair cleanly into half blocks
-    const { data, info } = await pipeline
-        .resize(width, height, { fit: "fill" })
+    // row holds two pixels, so square pixels keep the picture's proportions. With
+    // a height cap, scale to fit within width × (height rows) so a tall image
+    // stays inside the box instead of overflowing.
+    let targetW = width;
+    let targetH = Math.round(width * (srcHeight / srcWidth));
+    if (opts.height && opts.height > 0) {
+        const maxPxH = Math.floor(opts.height) * 2;
+        const scale = Math.min(width / srcWidth, maxPxH / srcHeight);
+        targetW = Math.max(1, Math.round(srcWidth * scale));
+        targetH = Math.round(srcHeight * scale);
+    }
+    targetH = Math.max(2, targetH);
+    if (targetH % 2 === 1)
+        targetH += 1; // even rows pair cleanly into half blocks
+    const { data, info } = await sharp(source)
+        .resize(targetW, targetH, { fit: "fill" })
         .ensureAlpha()
         .raw()
         .toBuffer({ resolveWithObject: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixelati",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn any image into truecolor terminal art using half-block characters.",
   "type": "module",
   "bin": {