pixeli 0.1.1 → 0.1.3

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Pakdad Mousavi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Pixeli (Pre-release)
 
-A lightweight command-line tool for merging multiple images into customizable grid layouts.
+# Pixeli (Pre-release) [![npm version](https://img.shields.io/badge/npm-v0.1.1-blue)](https://www.npmjs.com/package/pixeli) [![License](https://img.shields.io/github/license/pakdad-mousavi/pixeli)](./LICENSE)
+
+<img src="./assets/logo.svg" width="150" align="right">
+
+**Pixeli** is a lightweight and flexible command-line tool for merging multiple images into clean, customizable grid layouts. It’s designed for speed and simplicity, making it ideal for generating collages, previews, gallery layouts, inspiration boards, and composite images without relying on heavy desktop software.
+
+Pixeli uses Sharp, a Node.js wrapper for the libvips library which is based on C. This makes it an extremely fast tool with support for PNG, JPG, GIF, SVG, AVIF, etc.
+
+The tool currently supports two main layout modes: ***Grid*** and ***Masonry*** (horizontal / vertical). Each of them provide a distinct visual style to match a project's needs, for example:
+
+| Grid (1:1 images) | Contact Sheet Grid |
+|---|---|
+| <img src="samples/grid.png" width="400"> | <img src="samples/grid-with-captions.png" width="400"> |
+| **Masonry (Horizontal)** | **Masonry (Vertical)** |
+| <img src="samples/masonry-horizontal.png" width="400"> | <img src="samples/masonry-vertical.png" width="400"> |
+
+# Installation
+Pixeli can be installed using NPM. Simply run the following command to install it globally on your machine:
+```bash
+npm i -g pixeli
+```
+
+# Quick Examples
+To run these examples, you can visit the [GitHub Repository](https://github.com/pakdad-mousavi/pixeli) and use the images in the [Samples](https://github.com/pakdad-mousavi/pixeli/blob/main/samples/) directory, if you don't already have your own set of images.
+
+All merge commands are under the `pixeli merge` command and can be used like so: `pixeli merge [merge-mode] [options]`
+
+## Basic Grid
+To create a basic grid with 1:1 images, you can use the grid merge command. You'll also need to provide the individual filepaths to use, or use the `-rd` (--recursive and --directory) flags to get all the images from the specified directory:
+```bash
+pixeli merge grid -rd ./samples/images
+```
+
+Without the `-r` flag, only the images in the directory will be scanned, and any sub-directories will be ignored.
+
+## Grid with Rectangular Images
+To create a grid with images that all have the same aspect ratio, you can specify the aspect ratio to use for all images using the `--ar` flag:
+```bash
+pixeli merge grid -rd ./samples/images --ar 16:9
+```
+
+## Grid with 8 Columns
+You can also customize the number of columns that you'd like the final image to have using the `-c` flag, followed by the number of columns:
+```bash
+pixeli merge grid -rd ./samples/images -c 8
+```
+
+## Contact Sheet
+Contact sheet style grids can also be made using pixeli. To include each file name under its respective image, the `--ca` flag can be used:
+```bash
+pixeli merge grid -rd ./samples/images --ca
+```
+
+The caption color can also be specified using the `--cc` flag, followed by a hex color:
+```bash
+pixeli merge grid -rd ./samples/images --ca --cc "#ff0000"
+```
+
+## Masonry Layout
+To create a masonry style image, you can use the masonry merge command. The `-rd` flag is used to specify which directory to use, and the canvas width can be specified using the `--cvw` flag:
+```bash
+pixeli merge masonry -rd ./samples/images --cvw 4000
+```
+
+By default, the masonry merge command uses a horizontal orientation, but a vertical one can be specified using the `--or` flag, followed by the `--cvh` to specify the canvas height:
+```bash
+pixeli merge masonry -rd ./samples/images --or vertical --cvh 4000
+```
+
+# Full Documentation
+
+## `pixeli merge grid`
+Usage: `pixeli merge grid [options] <input...> -o <output>`
+
+The grid mode arranges images into a clean, uniform grid with fixed columns and automatic row calculation. The table below displays all of the options available to this command:
+| Option/Flag                                     | Default                | Description                                                                                                                                                                              |
+| ----------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--ar`, `--aspect-ratio <width/height\|number>` | `1:1`                  | Sets the **per-image aspect ratio**. Accepts ratio expressions (`16/9`, `4:3`) or decimal values (`1.777`). Images are scaled as needed to match this ratio before placement.            |
+| `-w`, `--image-width <px>`                      | *smallest input width* | Sets the **final width of each processed image** in the grid. The height is derived automatically based on the chosen aspect ratio.                                                      |
+| `-c`, `--columns <n>`                           | `4`                    | Defines how many **images per row** are placed in the grid. The total number of rows is calculated from the number of inputs.                                                            |
+| `--ca`, `--caption`                             | `false`                | Enables **automatic captions** under each image. Captions are derived from the filename (with extensions).                                                                               |
+| `--cc`, `--caption-color <hex>`                 | `#000000`              | HEX color value for caption text (e.g., `#ffffff`, `#ff9900`). Affects all captions uniformly.                                                                                           |
+| `--mcs`, `--max-caption-size <pt>`              | `100`                  | Sets the **maximum allowed caption font size**. Useful when images are extremely large and the caption is not big enough. The renderer may auto-reduce the font size if necessary.       |
+
+## `pixeli merge masonry`
+Usage: `pixeli merge masonry [options] <input...> -o <output>`
+
+The masonry mode preserves each image’s natural shape, creating an organic brick-wall layout similar to Pinterest boards.
+
+| Option/Flag                                          | Default                 | Description                                                                                                                                                   |
+| ---------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--rh`, `--row-height <px>`                          | *smallest input height* | Sets the **target height for all images in a row** when using `horizontal` orientation. Images are scaled proportionally based on this height.                |
+| `--cw`, `--column-width <px>`                        | *smallest input width*  | Sets the **target width for all images in a column** when using `vertical` orientation. Images are scaled proportionally based on this width.                 |
+| `--cvw`, `--canvas-width <px>`                       | –                       | Sets the **fixed width** of the final output canvas. Required when using a `horizontal` orientation to know when to break a row.                              |
+| `--cvh`, `--canvas-height <px>`                      | –                       | Sets the **fixed height** of the final output canvas. Required when using a `vertical` orientation to know when to break a column.                            |
+| `--or`, `--orientation <horizontal\|vertical>`       | `horizontal`            | Determines the **flow direction** of the masonry layout. `horizontal` creates rows of varying widths; `vertical` creates columns of varying heights.          |
+| `--ha`, `--h-align <left\|center\|right\|justified>` | `justified`             | Controls **horizontal alignment** of rows when in `horizontal` orientation. `justified` overfills each row and crops the final image to fill up the canvas.   |
+| `--va`, `--v-align <top\|middle\|bottom\|justified>` | `justified`             | Controls **vertical alignment** of columns when in `vertical` orientation. `justified` overfills each column and crops the final image to fill up the canvas. |
+
+# License
+This project is licensed under the [MIT License](./LICENSE).

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

@@ -10,15 +10,15 @@ import {
   handleError,
   writeImage,
 } from '../lib/helpers/utils.js';
-import { validateAspectOptions } from '../lib/helpers/validations.js';
+import { validateGridOptions } from '../lib/helpers/validations.js';
 import { loadImages } from '../lib/helpers/loadImages.js';
-import { aspectMerge } from '../lib/merges/aspect-merge/index.js';
+import { gridMerge } from '../lib/merges/grid-merge/index.js';
 
-const aspectCommand = new Command('aspect');
+const gridCommand = new Command('grid');
 
-aspectCommand
-  .description('Same aspect ratio, but not necessarily 1:1')
-  .option('--ar, --aspect-ratio <width/height|number>', 'The aspect ratio of all the images (examples: 16/9, 4:3, 1.777)', null)
+gridCommand
+  .description('Arranges images in an organized grid.')
+  .option('--ar, --aspect-ratio <width/height|number>', 'The aspect ratio of all the images (examples: 16/9, 4:3, 1.777)', '1:1')
   .option('-w, --image-width <px>', 'The width of each image, defaults to the smallest image', null)
   .option('-c, --columns <n>', 'The number of columns', 4)
   .option('--ca, --caption', 'Whether to caption each image', false)
@@ -31,7 +31,7 @@ aspectCommand
 const main = async (files, opts) => {
   // Collect and validate parameters
   try {
-    const validatedParams = getValidatedParams(files, opts, validateAspectOptions);
+    const validatedParams = getValidatedParams(files, opts, validateGridOptions);
 
     // Load images, create grid, and write grid on disk
     await generateAndSaveGrid(validatedParams);
@@ -56,7 +56,7 @@ const generateAndSaveGrid = async (validatedParams) => {
     if (!confirmation) return;
   }
 
-  const grid = await aspectMerge(files, images, validatedParams);
+  const grid = await gridMerge(files, images, validatedParams);
   const success = await writeImage(grid, validatedParams.output);
 
   // Display success message
@@ -65,5 +65,5 @@ const generateAndSaveGrid = async (validatedParams) => {
   }
 };
 
-addSharedOptions(aspectCommand);
-export default aspectCommand;
+addSharedOptions(gridCommand);
+export default gridCommand;

package/commands/merge.js

@@ -1,12 +1,10 @@
 import { Command } from 'commander';
-import squareCommand from './square.js';
 import masonryCommand from './masonry.js';
-import aspectCommand from './aspect.js';
+import gridCommand from './grid.js';
 
 const mergeCommand = new Command('merge').description('Merge images into a grid layout.');
 
-mergeCommand.addCommand(squareCommand);
 mergeCommand.addCommand(masonryCommand);
-mergeCommand.addCommand(aspectCommand);
+mergeCommand.addCommand(gridCommand);
 
 export default mergeCommand;

package/lib/helpers/validations.js

@@ -40,50 +40,6 @@ export const validateSharedOptions = (sharedOptions) => {
   return formattedParams;
 };
 
-export const validateSquareOptions = (sharedOptions, squareOptions) => {
-  // Extract params
-  const { fitMode, imageSize, paddingColor, columns, caption, captionColor, maxCaptionSize } = squareOptions;
-
-  // Define fit modes for validation
-  const FIT_MODES = ['contain', 'cover'];
-
-  if (!FIT_MODES.includes(fitMode)) {
-    throw new Error('Invalid fit mode. Choose one of the following: ' + FIT_MODES.join(', '));
-  }
-
-  if (imageSize && (isNaN(imageSize) || !Number.isInteger(Number(imageSize)) || Number(imageSize) < 1)) {
-    throw new Error('--image-size must be a positive integer.');
-  }
-
-  if (paddingColor !== 'transparent' && !isValidHexadecimal(paddingColor)) {
-    throw new Error('--padding-color must be a valid hexadecimal value.');
-  }
-
-  if (isNaN(columns) || !Number.isInteger(Number(columns)) || Number(columns) < 1) {
-    throw new Error('--columns must be a positive integer.');
-  }
-
-  if (isNaN(maxCaptionSize) || !Number.isInteger(Number(maxCaptionSize)) || Number(maxCaptionSize) < 2) {
-    throw new Error('--max-caption-size must be a positive integer >= 2 (minimum caption size).');
-  }
-
-  if (!isValidHexadecimal(captionColor)) {
-    throw new Error('--caption-color must be a valid hexadecimal value.');
-  }
-
-  const formattedParams = {
-    fitMode,
-    imageSize: Number(imageSize) || null,
-    paddingColor: paddingColor === 'transparent' ? { r: 0, g: 0, b: 0, alpha: 0 } : paddingColor,
-    columns: Number(columns),
-    caption,
-    captionColor,
-    maxCaptionSize,
-  };
-
-  return formattedParams;
-};
-
 export const validateMasonryOptions = (sharedOptions, masonryOptions) => {
   // Extract params
   const { gap } = sharedOptions;
@@ -202,14 +158,9 @@ export const validateMasonryOptions = (sharedOptions, masonryOptions) => {
   return params;
 };
 
-export const validateAspectOptions = (sharedOptions, squareOptions) => {
+export const validateGridOptions = (sharedOptions, gridOptions) => {
   // Extract params
-  const { aspectRatio, imageWidth, columns, caption, captionColor, maxCaptionSize } = squareOptions;
-
-  // Ensure aspect ratio is given
-  if (!aspectRatio) {
-    throw new Error('--aspect-ratio must be provided.');
-  }
+  const { aspectRatio, imageWidth, columns, caption, captionColor, maxCaptionSize } = gridOptions;
 
   // Ensure aspect ratio is valid
   const parsedAspectRatio = parseAspectRatio(aspectRatio);

package/lib/merges/{aspect-merge → grid-merge}/index.js

@@ -3,7 +3,7 @@ import sharp from 'sharp';
 import { getSmallestImageDimensions, getFontSize, createSvgTextBuffer } from '../merge-utils.js';
 import { progressBar, WRITING_TO_FILE_PERCENTAGE } from '../../helpers/progressBar.js';
 
-export const aspectMerge = async (files, images, validatedParams) => {
+export const gridMerge = async (files, images, validatedParams) => {
   // Destructure params
   const { aspectRatio, imageWidth, columns, gap, canvasColor, caption, captionColor, maxCaptionSize } = validatedParams;
 
@@ -16,7 +16,7 @@ export const aspectMerge = async (files, images, validatedParams) => {
     return image.resize({
       width,
       height,
-      fit: 'fill',
+      fit: 'cover',
     });
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixeli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "A lightweight command-line tool for merging multiple images into customizable grid layouts.",
   "homepage": "https://github.com/pakdad-mousavi/pixeli#readme",
   "bugs": {
@@ -22,6 +22,13 @@
     "/bin",
     "/commands"
   ],
+  "keywords": [
+    "cli",
+    "nodejs",
+    "npm",
+    "image-processing",
+    "image-merge"
+  ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },

package/commands/square.js

@@ -1,71 +0,0 @@
-import { Command } from 'commander';
-import chalk from 'chalk';
-import {
-  addSharedOptions,
-  cliConfirm,
-  displayInfoMessage,
-  displaySuccessMessage,
-  displayWarningMessage,
-  getValidatedParams,
-  handleError,
-  writeImage,
-} from '../lib/helpers/utils.js';
-import { validateSquareOptions } from '../lib/helpers/validations.js';
-import { loadImages } from '../lib/helpers/loadImages.js';
-import { squareMerge } from '../lib/merges/square-merge/index.js';
-
-const squareCommand = new Command('square');
-
-squareCommand
-  .description('Use a uniform grid layout (all images are 1:1)')
-  .option('-m, --fit-mode <contain|cover>', 'Determines how to fit the images in their cells', 'contain')
-  .option('--is, --image-size <px>', 'The width and height of each image, defaults to the smallest image', null)
-  .option('-p, --padding-color <hex|transparent>', 'Image padding color', 'transparent')
-  .option('-c, --columns <n>', 'The number of columns', 4)
-  .option('--ca, --caption', 'Whether to caption each image', false)
-  .option('--cc, --caption-color <hex>', 'Caption color', '#000000')
-  .option('--mcs, --max-caption-size <pt>', 'The maximum allowed caption size', 100)
-  .action(async (files, opts) => {
-    await main(files, opts);
-  });
-
-const main = async (files, opts) => {
-  // Collect and validate parameters
-  try {
-    const validatedParams = getValidatedParams(files, opts, validateSquareOptions);
-    // console.log(validatedParams);
-
-    // Load images, create grid, and write grid on disk
-    await generateAndSaveGrid(validatedParams);
-
-    // Output success message
-  } catch (e) {
-    handleError(e);
-  }
-};
-
-const generateAndSaveGrid = async (validatedParams) => {
-  const { files, images, ignoredFiles } = await loadImages(validatedParams);
-
-  // Display warnings if needed
-  if (ignoredFiles.length) {
-    displayWarningMessage('\nThese files will be ignored due to unsupported formats:');
-    for (const file of ignoredFiles) {
-      displayInfoMessage(file);
-    }
-
-    const confirmation = await cliConfirm('\nAre you sure you want to continue?');
-    if (!confirmation) return;
-  }
-
-  const grid = await squareMerge(files, images, validatedParams);
-  const success = await writeImage(grid, validatedParams.output);
-
-  // Display success message
-  if (success) {
-    displaySuccessMessage(`\nImage has been created successfully: ${chalk.bold(validatedParams.output)}\n`);
-  }
-};
-
-addSharedOptions(squareCommand);
-export default squareCommand;

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

@@ -1,141 +0,0 @@
-import path from 'node:path';
-import sharp from 'sharp';
-import { createSvgTextBuffer, getFontSize, getSmallestImageDimensions } from '../merge-utils.js';
-import { progressBar, WRITING_TO_FILE_PERCENTAGE } from '../../helpers/progressBar.js';
-
-export const squareMerge = async (files, images, opts) => {
-  const { gap, canvasColor, fitMode, imageSize, paddingColor, columns, caption, captionColor, maxCaptionSize } = opts;
-
-  // Determine target size
-  let newImageSize;
-  if (imageSize) {
-    // Use user-provided size directly
-    newImageSize = imageSize;
-  } else {
-    // Use smallest dimensions if imageSize is not provided
-    const { smallestWidth, smallestHeight } = await getSmallestImageDimensions(images);
-    newImageSize = Math.min(smallestWidth, smallestHeight);
-  }
-
-  // Convert / normalize images (square, pad/crop, resize)
-  const normalizedImages = await normalizeImages(images, paddingColor, newImageSize, fitMode);
-
-  // Lay images in a grid and return
-  const grid = await layImagesInGrid({
-    files,
-    images: normalizedImages,
-    columns,
-    size: newImageSize,
-    gap,
-    canvasColor,
-    caption,
-    captionColor,
-    maxCaptionSize,
-  });
-  return grid;
-};
-
-export const layImagesInGrid = async (opts) => {
-  const CAPTION_HEIGHT_TO_CANVAS_WIDTH_RATIO = 0.04;
-  const { files, images, columns, size, gap, canvasColor, caption, captionColor, maxCaptionSize } = opts;
-
-  // Use 5% of images.length for writing to file
-  const fileWriteAmount = Math.ceil(images.length * WRITING_TO_FILE_PERCENTAGE);
-  progressBar.start(images.length + fileWriteAmount, 0, {
-    stage: 'Merging images',
-  });
-
-  // Calculate base variables
-  const rows = Math.ceil(images.length / columns);
-  const canvasWidth = columns * size + (columns + 1) * gap;
-  const captionHeight = Math.floor(canvasWidth * CAPTION_HEIGHT_TO_CANVAS_WIDTH_RATIO);
-
-  // Get filenames and fontsize if needed
-  let filenames = null;
-  let fontSize = null;
-  if (caption) {
-    filenames = files.map((file) => path.basename(file));
-
-    const longestFilename = filenames.reduce((longest, current) => {
-      return current.length > longest.length ? current : longest;
-    });
-
-    fontSize = await getFontSize({
-      text: longestFilename,
-      maxWidth: size,
-      maxHeight: captionHeight,
-      initialFontSize: maxCaptionSize,
-    });
-  }
-
-  const minimumCanvasHeight = rows * size + (rows + 1) * gap;
-  const canvasHeight = caption ? minimumCanvasHeight + rows * captionHeight : minimumCanvasHeight;
-
-  // Create blank canvas
-  let canvas = sharp({
-    limitInputPixels: false,
-    create: {
-      width: canvasWidth,
-      height: canvasHeight,
-      channels: 4,
-      background: canvasColor,
-    },
-  });
-
-  // Build composite array
-  const composites = [];
-
-  for (let row = 0; row < rows; row++) {
-    for (let col = 0; col < columns; col++) {
-      const idx = row * columns + col;
-      if (idx >= images.length) break;
-
-      const x = gap + col * (size + gap);
-      const y = caption ? gap + row * (size + gap + captionHeight) : gap + row * (size + gap);
-
-      composites.push({
-        input: await images[idx].toBuffer(), // ensure buffer
-        left: x,
-        top: y,
-      });
-
-      // Add caption if required
-      if (caption) {
-        // Create text
-        const svgBuffer = createSvgTextBuffer({
-          text: filenames[idx],
-          maxWidth: size,
-          maxHeight: captionHeight,
-          fontSize,
-          fill: captionColor,
-        });
-
-        // Add text to composites
-        composites.push({
-          input: svgBuffer,
-          left: x,
-          top: y + size,
-        });
-
-        // Update progress bar
-        progressBar.increment();
-      }
-    }
-  }
-
-  // Composite all images at once
-  canvas = canvas.composite(composites);
-
-  return canvas;
-};
-
-const normalizeImages = async (images, paddingColor, targetSize, fitMode) => {
-  return images.map((image) =>
-    image.resize({
-      fit: fitMode,
-      width: targetSize,
-      height: targetSize,
-      background: paddingColor,
-    })
-  );
-};