pixeli 0.1.0

package/README.md

@@ -0,0 +1,3 @@
+# Pixeli (Pre-release)
+
+A lightweight command-line tool for merging multiple images into customizable grid layouts.

package/bin/pixeli.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import mergeCommand from '../commands/merge.js';
+import { handleError } from '../lib/helpers/utils.js';
+
+const program = new Command();
+
+// Define program
+program
+  .name('pixeli')
+  .description('A lightweight command-line tool for merging multiple images into customizable grid layouts.')
+  .version('1.0.0');
+
+// Add subcommands
+program.addCommand(mergeCommand);
+
+// Parse arguments
+try {
+  program.parse();
+} catch (e) {
+  handleError(e);
+}

package/commands/aspect.js

@@ -0,0 +1,69 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import {
+  addSharedOptions,
+  cliConfirm,
+  displayInfoMessage,
+  displaySuccessMessage,
+  displayWarningMessage,
+  getValidatedParams,
+  handleError,
+  writeImage,
+} from '../lib/helpers/utils.js';
+import { validateAspectOptions } from '../lib/helpers/validations.js';
+import { loadImages } from '../lib/helpers/loadImages.js';
+import { aspectMerge } from '../lib/merges/aspect-merge/index.js';
+
+const aspectCommand = new Command('aspect');
+
+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)
+  .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)
+  .option('--cc, --caption-color <hex>', 'Image 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, validateAspectOptions);
+
+    // 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 aspectMerge(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(aspectCommand);
+export default aspectCommand;

package/commands/masonry.js

@@ -0,0 +1,70 @@
+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';
+
+const masonryCommand = new Command('masonry');
+
+masonryCommand
+  .description("Use a ragged-grid layout, preserves images' aspect ratios")
+  .option('--rh, --row-height <px>', 'The height of each row, defaults to the smallest image height', null)
+  .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)
+  .action((files, opts) => {
+    main(files, opts);
+  });
+
+const main = async (files, opts) => {
+  try {
+    // Collect and validate parameters
+    const validatedParams = getValidatedParams(files, opts, validateMasonryOptions);
+
+    // Load images, create grid, and write grid on disk
+    generateAndSaveGrid(validatedParams);
+
+    // Output success message
+  } catch (e) {
+    handleError(e);
+  }
+};
+
+const generateAndSaveGrid = async (validatedParams) => {
+  const { 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 masonryMerge(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(masonryCommand);
+export default masonryCommand;

package/commands/merge.js

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

package/commands/square.js

@@ -0,0 +1,71 @@
+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/helpers/loadImages.js

@@ -0,0 +1,84 @@
+import sharp from 'sharp';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isSupportedInputImage, shuffleTogether } from './utils.js';
+
+const MAX_RECURSION_DEPTH = 10;
+
+export const loadImages = async ({ files, dir, recursive, shuffle }) => {
+  let ignoredFiles = [];
+  let filepaths = files;
+  let images = [];
+
+  if (files && files.length) {
+    // Load directly from provided file list
+    images = await loadFromFiles(files);
+  } else {
+    // Get all files from directory
+    const { skippedFiles, paths } = await getFilesFromDirectory(dir, recursive);
+    filepaths = paths;
+    ignoredFiles = skippedFiles;
+    images = await loadFromFiles(filepaths);
+  }
+
+  // Optional: shuffle filepaths and images together
+  if (shuffle) {
+    [filepaths, images] = shuffleTogether(filepaths, images);
+  }
+
+  return { images, files: filepaths, ignoredFiles };
+};
+
+const loadFromFiles = async (files) => {
+  const images = [];
+
+  for (const filepath of files) {
+    let image;
+
+    if (filepath.endsWith('.svg')) {
+      const svgBuffer = await fs.readFile(filepath);
+      image = sharp(svgBuffer);
+    } else {
+      image = sharp(filepath);
+    }
+
+    images.push(image);
+  }
+
+  return images;
+};
+
+const getFilesFromDirectory = async (dir, recursive, depth = 0) => {
+  // Use to collect warnings
+  const skippedFiles = [];
+
+  // Ensure recursiveness ends at the max recursion depth
+  if (depth >= MAX_RECURSION_DEPTH) return [];
+
+  // Get entries
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const file = path.join(entry.parentPath, entry.name);
+
+    // If the entry is a valid image file, add it to the list
+    if (entry.isFile() && isSupportedInputImage(entry.name)) {
+      files.push(file);
+    }
+    // If it is an invalid file format, add to skipped files
+    else if (entry.isFile() && !isSupportedInputImage(entry.name) && entry.name !== '.DS_Store') {
+      skippedFiles.push(entry.name);
+    }
+    // If it's a directory AND the recursive option is true,
+    // recursively get all the files
+    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);
+      skippedFiles.push(...dirObj.skippedFiles);
+    }
+  }
+
+  return { paths: files, skippedFiles };
+};

package/lib/helpers/progressBar.js

@@ -0,0 +1,20 @@
+import { SingleBar } from 'cli-progress';
+import chalk from 'chalk';
+
+const title = chalk.gray('Creating Image:');
+const bar = chalk.blue('{bar}');
+const percentage = chalk.yellow('{percentage}%');
+const eta = chalk.blue('ETA: ') + chalk.yellow('{eta_formatted}');
+const stage = chalk.gray('{stage}...');
+const divider = chalk.blue('|');
+
+export const WRITING_TO_FILE_PERCENTAGE = 0.05;
+
+export const progressBar = new SingleBar({
+  format: `${title} ${divider}${bar}${divider} ${percentage} ${divider} ${eta} ${divider} ${stage} `,
+  barCompleteChar: '\u2588',
+  barIncompleteChar: '\u2591',
+  stopOnComplete: true,
+  barsize: 40,
+  etaBuffer: 50,
+});

package/lib/helpers/utils.js

@@ -0,0 +1,208 @@
+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'];
+export const SUPPORTED_OUTPUT_FORMATS = ['.webp', '.gif', '.jpeg', '.jpg', '.png', '.tiff', '.avif'];
+
+// Message class used for logging
+export class Message {
+  constructor(text, type) {
+    this.text = text;
+    this.type = type;
+
+    switch (this.type) {
+      case 'error':
+        this.message = chalk.bold.red('Error: ') + chalk.red(this.text);
+        break;
+      case 'warning':
+        this.message = chalk.yellow(this.text);
+        break;
+      case 'success':
+        this.message = chalk.blue(this.text);
+        break;
+      case 'neutral':
+        this.message = chalk.gray(this.text);
+        break;
+      default:
+        this.message = chalk.gray(this.text);
+        break;
+    }
+  }
+}
+
+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>', '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);
+};
+
+export const parseAspectRatio = (input) => {
+  // return ratio straight away if its just a number
+  const ratio = Number(input);
+  if (ratio) {
+    return ratio;
+  }
+
+  const ratioRegex = /^\s*(\d+)\s*(\/|:|x)\s*(\d+)\s*$/i;
+  const match = input.match(ratioRegex);
+
+  // not parsable
+  if (!match) {
+    return null;
+  }
+
+  const width = parseInt(match[1], 10);
+  const height = parseInt(match[3], 10);
+
+  return width / height;
+};
+
+export const handleError = (error) => {
+  const m = new Message(error.message, 'error');
+  console.log(m.message);
+};
+
+export const displayInfoMessage = (message) => {
+  const m = new Message(message, 'neutral');
+  console.log(m.message);
+};
+
+export const displayWarningMessage = (message) => {
+  const m = new Message(message, 'warning');
+  console.log(m.message);
+};
+
+export const displaySuccessMessage = (message) => {
+  const m = new Message(message, 'success');
+  console.log(m.message);
+};
+
+export const cliConfirm = (message) => {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(chalk.yellow(`${message} (Y/n) `), (value) => {
+      const cleanedValue = value.toLowerCase().trim();
+      if (cleanedValue === 'y' || !cleanedValue.length) resolve(true);
+      else resolve(false);
+
+      console.log();
+      rl.close();
+    });
+  });
+};
+
+export const isSupportedInputImage = (filename) => {
+  for (const supportedFormat of SUPPORTED_INPUT_FORMATS) {
+    if (filename.endsWith(supportedFormat)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+export const isSupportedOutputImage = (filename) => {
+  for (const supportedFormat of SUPPORTED_OUTPUT_FORMATS) {
+    if (filename.endsWith(supportedFormat)) {
+      return true;
+    }
+  }
+  return false;
+};
+
+export const writeImage = async (image, output) => {
+  // Define file size limits
+  const LIMITS = {
+    png: 2_147_483_647,
+    jpg: 65_535,
+    jpeg: 65_535,
+    avif: 65_535,
+    webp: 16_383,
+  };
+
+  // Update progress bar stage
+  progressBar.update({ stage: 'Writing to file' });
+
+  try {
+    // Get image width and height
+    const { width, height } = await image.metadata();
+    const format = path.extname(output).replaceAll('.', '');
+
+    // Ensure image can be encoded in the respective format
+    const formatLimit = LIMITS[format];
+    if (width > formatLimit || height > formatLimit) {
+      throw new Error(`image is too large for ${format} format.`);
+    }
+
+    // Write to file
+    await image.toFile(output);
+  } catch (e) {
+    // Complete the progress bar
+    progressBar.update(progressBar.getTotal());
+
+    // Handle any errors
+    const m = new Message('Failed to write image on disk: ' + e.message, 'error');
+    console.log('\n' + m.message);
+
+    return false;
+  }
+
+  // Complete the progress bar
+  progressBar.update(progressBar.getTotal());
+
+  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;
+
+  // While there remain elements to shuffle.
+  while (currentIndex !== 0) {
+    // Pick a remaining element.
+    randomIndex = Math.floor(Math.random() * currentIndex);
+    currentIndex--;
+
+    // And swap it with the current element.
+    [array[currentIndex], array[randomIndex]] = [array[randomIndex], array[currentIndex]];
+  }
+
+  return array;
+};
+
+export const shuffleTogether = (a, b) => {
+  // 1. Build array of indices
+  const indices = [...a.keys()];
+
+  // 2. Shuffle the indices using your Fisher-Yates
+  shuffleArray(indices);
+
+  // 3. Apply same permutation to both arrays
+  const aShuffled = indices.map((i) => a[i]);
+  const bShuffled = indices.map((i) => b[i]);
+
+  return [aShuffled, bShuffled];
+};