pixeli 0.1.2 → 0.1.4

package/README.md

@@ -1,5 +1,5 @@
 
-# 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)
+# Pixeli (Pre-release) [![npm version](https://img.shields.io/github/package-json/version/pakdad-mousavi/pixeli)](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">
 
@@ -15,18 +15,23 @@ The tool currently supports two main layout modes: ***Grid*** and ***Masonry***
 | **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:
+## 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
+You can also run pixeli directly with npx without installing it globally. This is convenient for quick experiments or one-off usage:
+```bash
+npx pixeli merge <subcommand> [options] <files...>
+```
+
+## 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
+### 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
@@ -34,19 +39,19 @@ 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
+### 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
+### 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
 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
@@ -57,21 +62,42 @@ The caption color can also be specified using the `--cc` flag, followed by a hex
 pixeli merge grid -rd ./samples/images --ca --cc "#ff0000"
 ```
 
-## Masonry Layout
+### 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:
+By default, the masonry merge command uses a horizontal flow, but a vertical one can be specified using the `-f` flag, followed by the `--cvh` to specify the canvas height:
 ```bash
-pixeli merge masonry -rd ./samples/images --or vertical --cvh 4000
+pixeli merge masonry -rd ./samples/images -f vertical --cvh 4000
 ```
 
-# Full Documentation
+## Full Documentation
+
+### pixeli merge
+Usage: `pixeli merge <subcommand> [options] <input...> -o <output>`
+
+The merge command is what allows you to create grids and mosaics with your images.
+| Subcommand | Description                                                                                                                                       | Options                                                          |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `grid`     | Merge images into a uniform **rows × columns grid**, optionally with captions and per-image aspect ratios.                                        | See [grid options table](#pixeli-merge-grid)                     |
+| `masonry`  | Merge images into a **dynamic masonry layout**, preserving natural image proportions. Supports vertical or horizontal flow and alignment options. | See [masonry options table](#pixeli-merge-masonry)               |
+
+The following options and flags are shared for all of the subcommands under the `pixeli merge` command:
+| Option                         | Default        | Description                                                                                                                        |
+| ------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `[files...]`                   | —              | Image file paths to merge. You can specify multiple files or if you prefer directories, use `--dir`.                               |
+| `-d`, `--dir <path>`           | —              | Path to a **directory containing images** to merge. Can be used instead of listing files individually.                             |
+| `-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.                                |
+| `--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.).              |
+
 
-## `pixeli merge grid`
-Usage: `pixeli merge grid [options] <input...> -o <output>`
+### pixeli merge grid
+Usage: `pixeli merge grid [options] [files...]`
 
 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                                                                                                                                                                              |
@@ -83,20 +109,20 @@ The grid mode arranges images into a clean, uniform grid with fixed columns and
 | `--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>`
+### pixeli merge masonry
+Usage: `pixeli merge masonry [options] [files...]`
 
 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
+| Option/Flag                                          | Default                 | Description                                                                                                                                            |
+| ---------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `--rh`, `--row-height <px>`                          | *smallest input height* | Sets the **target height for all images in a row** when using `horizontal` flow. 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` flow. 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` flow 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` flow to know when to break a column.                            |
+| `-f`, `--flow <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` flow. `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` flow. `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/masonry.js

@@ -22,9 +22,9 @@ masonryCommand
   .option('--cw, --column-width <px>', 'The width of each column, defaults to the smallest image width', null)
   .option('--cvw, --canvas-width <px>', 'The width of the canvas', null)
   .option('--cvh, --canvas-height <px>', 'The height of the canvas', null)
-  .option('--or, --orientation <horizontal|vertical>', 'The orientation of the masonry layout', 'horizontal')
-  .option('--ha, --h-align <left|center|right|justified>', 'Horizontal alignment of the grid (for horizontal orientations)', null)
-  .option('--va, --v-align <top|middle|bottom|justified>', 'Vertical alignment of the grid (for vertical orientations)', null)
+  .option('-f, --flow <horizontal|vertical>', 'The flow of the masonry layout', 'horizontal')
+  .option('--ha, --h-align <left|center|right|justified>', 'Horizontal alignment of the grid (for horizontal flows)', null)
+  .option('--va, --v-align <top|middle|bottom|justified>', 'Vertical alignment of the grid (for vertical flows)', null)
   .action((files, opts) => {
     main(files, opts);
   });

package/lib/helpers/utils.js

@@ -40,7 +40,7 @@ export const addSharedOptions = (cmd) => {
     .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>', 'Background color for canvas', '#ffffff')
+    .option('--bg, --canvas-color <hex|transparent>', 'Background color for canvas', '#ffffff')
     .option('-o, --output <file>', 'Output file path', './pixeli.png');
 };
 

package/lib/helpers/validations.js

@@ -43,15 +43,15 @@ export const validateSharedOptions = (sharedOptions) => {
 export const validateMasonryOptions = (sharedOptions, masonryOptions) => {
   // Extract params
   const { gap } = sharedOptions;
-  const { rowHeight, columnWidth, canvasWidth, canvasHeight, orientation, hAlign, vAlign } = masonryOptions;
+  const { rowHeight, columnWidth, canvasWidth, canvasHeight, flow, hAlign, vAlign } = masonryOptions;
 
   // Define orientations and alignments for validation
-  const ORIENTATIONS = ['horizontal', 'vertical'];
+  const FLOWS = ['horizontal', 'vertical'];
   const HORIZONTAL_ALIGNMENTS = ['left', 'center', 'right', 'justified'];
   const VERTICAL_ALIGNMENTS = ['top', 'middle', 'bottom', 'justified'];
 
   // Define orientation dependent options which are ignored if defined for the wrong orientation
-  const IGNORED_ORIENTATION_DEPENDENT_OPTIONS = {
+  const IGNORED_FLOW_DEPENDENT_OPTIONS = {
     horizontal: [
       {
         option: '--v-align',
@@ -83,8 +83,8 @@ export const validateMasonryOptions = (sharedOptions, masonryOptions) => {
   };
 
   // Validate orientations and alignments
-  if (!ORIENTATIONS.includes(orientation)) {
-    throw new Error('Invalid orientation. Choose one of the following: ' + ORIENTATIONS.join(', '));
+  if (!FLOWS.includes(flow)) {
+    throw new Error('Invalid orientation. Choose one of the following: ' + FLOWS.join(', '));
   }
 
   if (hAlign && !HORIZONTAL_ALIGNMENTS.includes(hAlign)) {
@@ -105,43 +105,37 @@ export const validateMasonryOptions = (sharedOptions, masonryOptions) => {
   }
 
   // Ensure canvas width is given
-  if (orientation === 'horizontal' && !canvasWidth) {
+  if (flow === 'horizontal' && !canvasWidth) {
     throw new Error('--canvas-width must be given.');
   }
   // and is a positive integer
-  else if (
-    orientation === 'horizontal' &&
-    (isNaN(canvasWidth) || !Number.isInteger(Number(canvasWidth)) || Number(canvasWidth) < 1)
-  ) {
+  else if (flow === 'horizontal' && (isNaN(canvasWidth) || !Number.isInteger(Number(canvasWidth)) || Number(canvasWidth) < 1)) {
     throw new Error('--canvas-width must be a positive integer.');
   }
   // and it accomodates for the minimum width needed
-  else if (orientation === 'horizontal' && canvasWidth <= gap * 2) {
+  else if (flow === 'horizontal' && canvasWidth <= gap * 2) {
     throw new Error(`--canvas-width must be greater than 2 gaps or ${gap * 2}px.`);
   }
 
   // Ensure canvas height is given
-  if (orientation === 'vertical' && !canvasHeight) {
+  if (flow === 'vertical' && !canvasHeight) {
     throw new Error('--canvas-height must be given.');
   }
   // and is a positive integer
-  else if (
-    orientation === 'vertical' &&
-    (isNaN(canvasHeight) || !Number.isInteger(Number(canvasHeight)) || Number(canvasHeight) < 1)
-  ) {
+  else if (flow === 'vertical' && (isNaN(canvasHeight) || !Number.isInteger(Number(canvasHeight)) || Number(canvasHeight) < 1)) {
     throw new Error('--canvas-height must be a positive integer.');
   }
   // and it accomodates for the minimum height needed
-  else if (orientation === 'vertical' && canvasHeight <= gap * 2) {
+  else if (flow === 'vertical' && canvasHeight <= gap * 2) {
     throw new Error(`--canvas-height must be greater than 2 gaps or ${gap * 2}px.`);
   }
 
   // Validate dependent options by showing warnings when incorrect parameters
   // are used with incorrect orientation
-  const ignoredOrientationOptions = IGNORED_ORIENTATION_DEPENDENT_OPTIONS[orientation];
-  for (const { option, value } of ignoredOrientationOptions) {
+  const ignoredFlowOptions = IGNORED_FLOW_DEPENDENT_OPTIONS[flow];
+  for (const { option, value } of ignoredFlowOptions) {
     if (value) {
-      displayWarningMessage(`"${option}" option is ignored due to ${orientation} orientation.`);
+      displayWarningMessage(`"${option}" option is ignored due to ${flow} flow.`);
     }
   }
 
@@ -150,7 +144,7 @@ export const validateMasonryOptions = (sharedOptions, masonryOptions) => {
     columnWidth: Number(columnWidth) || null,
     canvasHeight: Number(canvasHeight) || null,
     canvasWidth: Number(canvasWidth) || null,
-    orientation,
+    flow,
     hAlign,
     vAlign,
   };

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

@@ -2,7 +2,7 @@ import { calculateAvgWidth, calculateAvgHeight } from '../merge-utils.js';
 import { buildHorizontalMasonry } from './horizontal.js';
 import { buildVerticalMasonry } from './vertical.js';
 
-const ORIENTATION_DEFAULTS = {
+const FLOW_DEFAULTS = {
   horizontal: {
     needed: ['canvasWidth', 'rowHeight', 'hAlign'],
     defaults: {
@@ -20,15 +20,15 @@ const ORIENTATION_DEFAULTS = {
 };
 
 export const masonryMerge = async (images, opts) => {
-  const { orientation } = opts;
-  const params = await getOrientationSpecificParams(images, opts);
+  const { flow } = opts;
+  const params = await getFlowSpecificParams(images, opts);
 
-  return await generateGrid(orientation, images, params);
+  return await generateGrid(flow, images, params);
 };
 
-const getOrientationSpecificParams = async (images, currentParams) => {
-  const { orientation, gap, canvasColor } = currentParams;
-  const config = ORIENTATION_DEFAULTS[orientation];
+const getFlowSpecificParams = async (images, currentParams) => {
+  const { flow, gap, canvasColor } = currentParams;
+  const config = FLOW_DEFAULTS[flow];
 
   const output = { gap, canvasColor };
 
@@ -48,8 +48,8 @@ const getOrientationSpecificParams = async (images, currentParams) => {
   return output;
 };
 
-const generateGrid = async (orientation, images, params) => {
-  if (orientation === 'horizontal') {
+const generateGrid = async (flow, images, params) => {
+  if (flow === 'horizontal') {
     return await buildHorizontalMasonry(images, params);
   } else {
     return buildVerticalMasonry(images, params);

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

@@ -16,10 +16,6 @@ export const buildVerticalMasonry = async (images, params) => {
 
   // Split images into columns, then calculate canvasWidth
   const columns = await splitIntoColumns(scaledImages, canvasHeight, gap, vAlign);
-  console.log(columns.length);
-  columns.forEach((col) => {
-    console.log(col.length);
-  });
   const canvasWidth = columns.length * columnWidth + (columns.length + 1) * gap;
 
   // Create and return grid of images
@@ -63,9 +59,6 @@ const createMasonryLayout = async (cols, columnWidth, canvasWidth, canvasHeight,
         const buffer = await finalizedImage.resize(resizeOptions).toBuffer();
         finalizedImage = sharp(buffer);
         finalizedMeta = await finalizedImage.metadata();
-
-        // Update progress bar
-        progressBar.increment();
       }
 
       composites.push({
@@ -75,6 +68,9 @@ const createMasonryLayout = async (cols, columnWidth, canvasWidth, canvasHeight,
       });
 
       y += finalizedMeta.height + gap;
+
+      // Update progress bar
+      progressBar.increment();
     }
 
     y = gap;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixeli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "A lightweight command-line tool for merging multiple images into customizable grid layouts.",
   "homepage": "https://github.com/pakdad-mousavi/pixeli#readme",
   "bugs": {
@@ -10,6 +10,12 @@
     "type": "git",
     "url": "git+https://github.com/pakdad-mousavi/pixeli.git"
   },
+  "licenses": [
+    {
+      "type": "MIT",
+      "url": "https://github.com/pakdad-mousavi/pixeli/blob/main/LICENSE"
+    }
+  ],
   "bin": {
     "pixeli": "bin/pixeli.js"
   },
@@ -22,6 +28,13 @@
     "/bin",
     "/commands"
   ],
+  "keywords": [
+    "cli",
+    "nodejs",
+    "npm",
+    "image-processing",
+    "image-merge"
+  ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },