pixeli 0.1.5 → 0.1.6

package/README.md

@@ -92,6 +92,7 @@ The following options and flags are shared for all of the subcommands under the
 | `-r`, `--recursive`            | `false`        | Include **images in all subdirectories** of the specified directory recursively.                                                   |
 | `--sh`, `--shuffle`            | `false`        | **Randomize the order** of images before merging. Useful for creating visually varied grids or collages.                           |
 | `-g`, `--gap <px>`             | `50`           | **Spacing (in pixels) between images** in the layout. Applies to both horizontal and vertical gaps.                                |
+| `--cr`, `--corner-radius <px>` | `0`            | How much to **round the corners** of each image in pixels.                                                                         |
 | `--bg`, `--canvas-color <hex>` | `#ffffff`      | Sets the **background color of the canvas**. Accepts HEX values (e.g., `#000000` for black).                                       |
 | `-o`, `--output <file>`        | `./pixeli.png` | Path for the **merged output image**. The format is inferred from the file extension (`.png`, `.jpg`, `.webp`, etc.).              |
 
@@ -126,3 +127,6 @@ The masonry mode preserves each image’s natural shape, creating an organic bri
 
 ## License
 This project is licensed under the [MIT License](./LICENSE).
+
+## Other
+This project was submitted to [Hack Club](https://hackclub.com/), a group consisting of over 100,000 teen hackers from around the world who work on cool projects and get to participate in awesome programs like [Midnight](https://midnight.hackclub.com).

package/bin/pixeli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import mergeCommand from '../commands/merge.js';
-import { handleError } from '../lib/helpers/utils.js';
+import mergeCommand from '../commands/merge/index.js';
+import { configureCommandErrors, handleError } from '../lib/helpers/utils.js';
 
 const program = new Command();
 
@@ -15,6 +15,9 @@ program
 // Add subcommands
 program.addCommand(mergeCommand);
 
+// Configure errors for all subcommands
+configureCommandErrors(program);
+
 // Parse arguments
 try {
   program.parse();

package/commands/{grid.js → merge/grid.js}

@@ -1,18 +1,17 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import {
-  addSharedOptions,
   cliConfirm,
   displayInfoMessage,
   displaySuccessMessage,
   displayWarningMessage,
-  getValidatedParams,
   handleError,
   writeImage,
-} from '../lib/helpers/utils.js';
-import { validateGridOptions } from '../lib/helpers/validations.js';
-import { loadImages } from '../lib/helpers/loadImages.js';
-import { gridMerge } from '../lib/merges/grid-merge/index.js';
+} from '../../lib/helpers/utils.js';
+import { addSharedOptions, getValidatedParams } from './helpers/utils.js';
+import { validateGridOptions } from './helpers/validations.js';
+import { loadImages } from '../../lib/helpers/loadImages.js';
+import { gridMerge } from '../../lib/merges/grid-merge/index.js';
 
 const gridCommand = new Command('grid');
 
@@ -31,7 +30,7 @@ gridCommand
 const main = async (files, opts) => {
   // Collect and validate parameters
   try {
-    const validatedParams = getValidatedParams(files, opts, validateGridOptions);
+    const validatedParams = await getValidatedParams(files, opts, validateGridOptions);
 
     // Load images, create grid, and write grid on disk
     await generateAndSaveGrid(validatedParams);

package/commands/merge/helpers/utils.js

@@ -0,0 +1,20 @@
+import { validateSharedOptions } from './validations.js';
+
+export const addSharedOptions = (cmd) => {
+  return cmd
+    .argument('[files...]', 'Image filepaths to merge (use --dir for directories)')
+    .option('-d, --dir <path>', 'Directory of images to merge')
+    .option('-r, --recursive', 'Recursively include subdirectories', false)
+    .option('--sh, --shuffle', 'Shuffle up images to randomize order in the grid', false)
+    .option('--cr, --corner-radius <px>', 'How much to round the corners of each image', 0)
+    .option('-g, --gap <px>', 'Gap between images', 50)
+    .option('--bg, --canvas-color <hex|transparent>', 'Background color for canvas', '#ffffff')
+    .option('-o, --output <file>', 'Output file path', './pixeli.png');
+};
+
+export const getValidatedParams = async (files, opts, validationFunc) => {
+  const params = { files, ...opts };
+  const sharedOptions = await validateSharedOptions(params);
+  const commandOptions = validationFunc(sharedOptions, params);
+  return { ...sharedOptions, ...commandOptions };
+};

package/{lib → commands/merge}/helpers/validations.js

@@ -1,24 +1,46 @@
+import fs from 'node:fs/promises';
+
 import {
   displayWarningMessage,
+  handleError,
   isSupportedOutputImage,
   isValidHexadecimal,
   parseAspectRatio,
   SUPPORTED_OUTPUT_FORMATS,
-} from './utils.js';
+} from '../../../lib/helpers/utils.js';
 
-export const validateSharedOptions = (sharedOptions) => {
+export const validateSharedOptions = async (sharedOptions) => {
   // Extract params
-  const { files, dir, recursive, shuffle, gap, canvasColor, output } = sharedOptions;
+  const { files, dir, recursive, shuffle, cornerRadius, gap, canvasColor, output } = sharedOptions;
 
   // Conduct validations
   if ((!files || !files.length) && !dir) {
     throw new Error('You must specify either [files...] or --dir.');
   }
 
+  // Ensure dir is a valid dir path
+  if (dir.length) {
+    let stats;
+
+    try {
+      stats = await fs.stat(dir);
+    } catch (e) {
+      throw new Error('Path does not exist.');
+    }
+
+    if (!stats.isDirectory()) {
+      throw new Error('Path is not a directory.');
+    }
+  }
+
   if (isNaN(gap) || !Number.isInteger(Number(gap)) || gap < 0) {
     throw new Error('--gap must be a positive integer.');
   }
 
+  if (isNaN(cornerRadius) || !Number.isInteger(Number(cornerRadius)) || cornerRadius < 0) {
+    throw new Error('--corner-radius must be a positive integer.');
+  }
+
   if (canvasColor !== 'transparent' && !isValidHexadecimal(canvasColor)) {
     throw new Error('--canvas-color must be a valid hexadecimal value.');
   }
@@ -32,6 +54,7 @@ export const validateSharedOptions = (sharedOptions) => {
     dir,
     recursive,
     shuffle,
+    cornerRadius: Number(cornerRadius),
     gap: Number(gap),
     canvasColor: canvasColor === 'transparent' ? { r: 0, g: 0, b: 0, alpha: 0 } : canvasColor,
     output,

package/commands/{masonry.js → merge/masonry.js}

@@ -1,18 +1,17 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
 import {
-  addSharedOptions,
   cliConfirm,
   displayInfoMessage,
   displaySuccessMessage,
   displayWarningMessage,
-  getValidatedParams,
   handleError,
   writeImage,
-} from '../lib/helpers/utils.js';
-import { validateMasonryOptions } from '../lib/helpers/validations.js';
-import { loadImages } from '../lib/helpers/loadImages.js';
-import { masonryMerge } from '../lib/merges/masonry-merge/index.js';
+} from '../../lib/helpers/utils.js';
+import { addSharedOptions, getValidatedParams } from './helpers/utils.js';
+import { validateMasonryOptions } from './helpers/validations.js';
+import { loadImages } from '../../lib/helpers/loadImages.js';
+import { masonryMerge } from '../../lib/merges/masonry-merge/index.js';
 
 const masonryCommand = new Command('masonry');
 
@@ -32,7 +31,7 @@ masonryCommand
 const main = async (files, opts) => {
   try {
     // Collect and validate parameters
-    const validatedParams = getValidatedParams(files, opts, validateMasonryOptions);
+    const validatedParams = await getValidatedParams(files, opts, validateMasonryOptions);
 
     // Load images, create grid, and write grid on disk
     generateAndSaveGrid(validatedParams);

package/lib/helpers/loadImages.js

@@ -53,7 +53,7 @@ const getFilesFromDirectory = async (dir, recursive, depth = 0) => {
   const skippedFiles = [];
 
   // Ensure recursiveness ends at the max recursion depth
-  if (depth >= MAX_RECURSION_DEPTH) return [];
+  if (depth >= MAX_RECURSION_DEPTH) return { paths: [], skippedFiles: [] };
 
   // Get entries
   const entries = await fs.readdir(dir, { withFileTypes: true });
@@ -75,7 +75,7 @@ const getFilesFromDirectory = async (dir, recursive, depth = 0) => {
     else if (recursive && entry.isDirectory() && !entry.isSymbolicLink()) {
       const dirpath = path.join(entry.parentPath, entry.name);
       const dirObj = await getFilesFromDirectory(dirpath, recursive, depth + 1);
-      files.push(...dirObj.paths);
+      files.push(...dirObj?.paths);
       skippedFiles.push(...dirObj.skippedFiles);
     }
   }

package/lib/helpers/utils.js

@@ -1,7 +1,6 @@
 import readline from 'node:readline';
 import path from 'node:path';
 import chalk from 'chalk';
-import { validateSharedOptions } from './validations.js';
 import { progressBar } from './progressBar.js';
 
 export const SUPPORTED_INPUT_FORMATS = ['.webp', '.gif', '.jpeg', '.jpg', '.png', '.tiff', '.avif', '.svg'];
@@ -33,17 +32,6 @@ export class Message {
   }
 }
 
-export const addSharedOptions = (cmd) => {
-  return cmd
-    .argument('[files...]', 'Image filepaths to merge (use --dir for directories)')
-    .option('-d, --dir <path>', 'Directory of images to merge')
-    .option('-r, --recursive', 'Recursively include subdirectories', false)
-    .option('--sh, --shuffle', 'Shuffle up images to randomize order in the grid', false)
-    .option('-g, --gap <px>', 'Gap between images', 50)
-    .option('--bg, --canvas-color <hex|transparent>', 'Background color for canvas', '#ffffff')
-    .option('-o, --output <file>', 'Output file path', './pixeli.png');
-};
-
 export const isValidHexadecimal = (str) => {
   const hexRegex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
   return hexRegex.test(str);
@@ -75,6 +63,25 @@ export const handleError = (error) => {
   console.log(m.message);
 };
 
+export const configureCommandErrors = (cmd) => {
+  // Configure error message for the current command
+  cmd.configureOutput({
+    writeErr: (str) => {
+      if (str.includes('error:')) {
+        const err = new Message(str.replace('error: ', ''), 'error');
+        return process.stderr.write(err.message);
+      }
+
+      process.stderr.write(str);
+    },
+  });
+
+  // Recursively configure error messages for all subcommands
+  for (const subCmd of cmd.commands) {
+    configureCommandErrors(subCmd);
+  }
+};
+
 export const displayInfoMessage = (message) => {
   const m = new Message(message, 'neutral');
   console.log(m.message);
@@ -169,13 +176,6 @@ export const writeImage = async (image, output) => {
   return true;
 };
 
-export const getValidatedParams = (files, opts, validationFunc) => {
-  const params = { files, ...opts };
-  const sharedOptions = validateSharedOptions(params);
-  const commandOptions = validationFunc(sharedOptions, params);
-  return { ...sharedOptions, ...commandOptions };
-};
-
 export const shuffleArray = (array) => {
   let currentIndex = array.length;
   let randomIndex;

package/lib/merges/grid-merge/index.js

@@ -1,11 +1,11 @@
 import path from 'node:path';
 import sharp from 'sharp';
-import { getSmallestImageDimensions, getFontSize, createSvgTextBuffer } from '../merge-utils.js';
+import { getSmallestImageDimensions, getFontSize, createSvgTextBuffer, roundImages } from '../merge-utils.js';
 import { progressBar, WRITING_TO_FILE_PERCENTAGE } from '../../helpers/progressBar.js';
 
 export const gridMerge = async (files, images, validatedParams) => {
   // Destructure params
-  const { aspectRatio, imageWidth, columns, gap, canvasColor, caption, captionColor, maxCaptionSize } = validatedParams;
+  const { aspectRatio, imageWidth, columns, gap, cornerRadius, canvasColor, caption, captionColor, maxCaptionSize } = validatedParams;
 
   // Calculate width if needed, and height from aspect ratio
   const width = imageWidth || (await getSmallestImageDimensions(images)).smallestWidth;
@@ -20,6 +20,9 @@ export const gridMerge = async (files, images, validatedParams) => {
     });
   });
 
+  // Round images if needed
+  const roundedImages = await roundImages(resizedImages, { width, height, cornerRadius });
+
   // Get filenames if needed
   let filenames = null;
   if (caption) {
@@ -28,7 +31,7 @@ export const gridMerge = async (files, images, validatedParams) => {
 
   // Lay images in a grid
   const gridParams = {
-    images: resizedImages,
+    images: roundedImages,
     width,
     height,
     columns,

package/lib/merges/masonry-merge/horizontal.js

@@ -1,9 +1,9 @@
 import sharp from 'sharp';
-import { scaleImages } from '../merge-utils.js';
+import { roundImages, scaleImages } from '../merge-utils.js';
 import { progressBar, WRITING_TO_FILE_PERCENTAGE } from '../../helpers/progressBar.js';
 
 export const buildHorizontalMasonry = async (images, params) => {
-  const { gap, canvasColor, canvasWidth, rowHeight, hAlign } = params;
+  const { gap, canvasColor, cornerRadius, canvasWidth, rowHeight, hAlign } = params;
 
   // Use 5% of images.length for writing to file
   const fileWriteAmount = Math.ceil(images.length * WRITING_TO_FILE_PERCENTAGE);
@@ -19,10 +19,10 @@ export const buildHorizontalMasonry = async (images, params) => {
   const canvasHeight = rows.length * rowHeight + (rows.length + 1) * gap;
 
   // Create and return grid of images
-  return await createMasonryLayout(rows, rowHeight, canvasWidth, canvasHeight, canvasColor, gap, hAlign);
+  return await createMasonryLayout(rows, rowHeight, canvasWidth, canvasHeight, canvasColor, cornerRadius, gap, hAlign);
 };
 
-const createMasonryLayout = async (rows, rowHeight, canvasWidth, canvasHeight, canvasColor, gap, hAlign) => {
+const createMasonryLayout = async (rows, rowHeight, canvasWidth, canvasHeight, canvasColor, cornerRadius, gap, hAlign) => {
   const canvas = sharp({
     limitInputPixels: false,
     create: {
@@ -66,8 +66,17 @@ const createMasonryLayout = async (rows, rowHeight, canvasWidth, canvasHeight, c
         finalizedMeta = await finalizedImage.metadata();
       }
 
+      // Round the finalized image
+      const roundingOptions = {
+        width: finalizedMeta.width,
+        height: finalizedMeta.height,
+        cornerRadius,
+      };
+
+      const roundedImage = (await roundImages([finalizedImage], roundingOptions))[0];
+
       composites.push({
-        input: await finalizedImage.toBuffer(),
+        input: await roundedImage.toBuffer(),
         left: x,
         top: y,
       });

package/lib/merges/masonry-merge/index.js

@@ -27,10 +27,10 @@ export const masonryMerge = async (images, opts) => {
 };
 
 const getFlowSpecificParams = async (images, currentParams) => {
-  const { flow, gap, canvasColor } = currentParams;
+  const { flow, gap, canvasColor, cornerRadius } = currentParams;
   const config = FLOW_DEFAULTS[flow];
 
-  const output = { gap, canvasColor };
+  const output = { gap, canvasColor, cornerRadius };
 
   for (const key of config.needed) {
     if (currentParams[key] != null) {

package/lib/merges/masonry-merge/vertical.js

@@ -1,9 +1,9 @@
 import sharp from 'sharp';
-import { scaleImages } from '../merge-utils.js';
+import { roundImages, scaleImages } from '../merge-utils.js';
 import { progressBar, WRITING_TO_FILE_PERCENTAGE } from '../../helpers/progressBar.js';
 
 export const buildVerticalMasonry = async (images, params) => {
-  const { gap, canvasColor, canvasHeight, columnWidth, vAlign } = params;
+  const { gap, canvasColor, cornerRadius, canvasHeight, columnWidth, vAlign } = params;
 
   // Use 5% of images.length for writing to file
   const fileWriteAmount = Math.ceil(images.length * WRITING_TO_FILE_PERCENTAGE);
@@ -19,10 +19,10 @@ export const buildVerticalMasonry = async (images, params) => {
   const canvasWidth = columns.length * columnWidth + (columns.length + 1) * gap;
 
   // Create and return grid of images
-  return await createMasonryLayout(columns, columnWidth, canvasWidth, canvasHeight, canvasColor, gap, vAlign);
+  return await createMasonryLayout(columns, columnWidth, canvasWidth, canvasHeight, canvasColor, cornerRadius, gap, vAlign);
 };
 
-const createMasonryLayout = async (cols, columnWidth, canvasWidth, canvasHeight, canvasColor, gap, vAlign) => {
+const createMasonryLayout = async (cols, columnWidth, canvasWidth, canvasHeight, canvasColor, cornerRadius, gap, vAlign) => {
   const composites = [];
 
   const canvas = sharp({
@@ -61,8 +61,17 @@ const createMasonryLayout = async (cols, columnWidth, canvasWidth, canvasHeight,
         finalizedMeta = await finalizedImage.metadata();
       }
 
+      // Round the finalized image
+      const roundingOptions = {
+        width: finalizedMeta.width,
+        height: finalizedMeta.height,
+        cornerRadius,
+      };
+
+      const roundedImage = (await roundImages([finalizedImage], roundingOptions))[0];
+
       composites.push({
-        input: await finalizedImage.toBuffer(),
+        input: await roundedImage.toBuffer(),
         left: x,
         top: y,
       });

package/lib/merges/merge-utils.js

@@ -33,7 +33,10 @@ export const scaleImages = async (images, { width = null, height = null }) => {
 
       let targetWidth, targetHeight;
 
-      if (width) {
+      if (width && height) {
+        targetWidth = width;
+        targetHeight = height;
+      } else if (width) {
         const f = width / meta.width;
         targetWidth = width;
         targetHeight = Math.floor(meta.height * f);
@@ -150,7 +153,24 @@ const escapeXML = (str) => {
   );
 };
 
-/*
-      
+export const roundImages = async (images, { width, height, cornerRadius }) => {
+  // Skip if the cornerRadius = zero
+  if (!cornerRadius) return images;
 
-*/
+  // Round images respectively
+  return await Promise.all(
+    images.map(async (image) => {
+      const mask = Buffer.from(`
+        <svg width="${width}" height="${height}">
+          <rect x="0" y="0" width="${width}" height="${height}" rx="${cornerRadius}" ry="${cornerRadius}" />
+          </svg>
+      `);
+
+      const buff = await image
+        .composite([{ input: mask, blend: 'dest-in' }])
+        .png()
+        .toBuffer();
+      return sharp(buff);
+    })
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixeli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "A lightweight command-line tool for merging multiple images into customizable grid layouts.",
   "homepage": "https://github.com/pakdad-mousavi/pixeli#readme",
   "bugs": {
@@ -36,6 +36,7 @@
     "chalk": "^5.6.2",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.2",
-    "sharp": "^0.34.5"
+    "sharp": "^0.34.5",
+    "table": "^6.9.0"
   }
 }