pixeli 0.1.0

package/lib/helpers/validations.js

@@ -0,0 +1,246 @@
+import {
+  displayWarningMessage,
+  isSupportedOutputImage,
+  isValidHexadecimal,
+  parseAspectRatio,
+  SUPPORTED_OUTPUT_FORMATS,
+} from './utils.js';
+
+export const validateSharedOptions = (sharedOptions) => {
+  // Extract params
+  const { files, dir, recursive, shuffle, gap, canvasColor, output } = sharedOptions;
+
+  // Conduct validations
+  if ((!files || !files.length) && !dir) {
+    throw new Error('You must specify either [files...] or --dir.');
+  }
+
+  if (isNaN(gap) || !Number.isInteger(Number(gap)) || gap < 0) {
+    throw new Error('--gap must be a positive integer.');
+  }
+
+  if (canvasColor !== 'transparent' && !isValidHexadecimal(canvasColor)) {
+    throw new Error('--canvas-color must be a valid hexadecimal value.');
+  }
+
+  if (!isSupportedOutputImage(output)) {
+    throw new Error('Invalid output format. Choose one of the following: ' + SUPPORTED_OUTPUT_FORMATS.join(', '));
+  }
+
+  const formattedParams = {
+    files: files || [],
+    dir,
+    recursive,
+    shuffle,
+    gap: Number(gap),
+    canvasColor: canvasColor === 'transparent' ? { r: 0, g: 0, b: 0, alpha: 0 } : canvasColor,
+    output,
+  };
+
+  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;
+  const { rowHeight, columnWidth, canvasWidth, canvasHeight, orientation, hAlign, vAlign } = masonryOptions;
+
+  // Define orientations and alignments for validation
+  const ORIENTATIONS = ['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 = {
+    horizontal: [
+      {
+        option: '--v-align',
+        value: vAlign,
+      },
+      {
+        option: '--canvas-height',
+        value: canvasHeight,
+      },
+      {
+        option: '--column-width',
+        value: columnWidth,
+      },
+    ],
+    vertical: [
+      {
+        option: '--h-align',
+        value: hAlign,
+      },
+      {
+        option: '--canvas-width',
+        value: canvasWidth,
+      },
+      {
+        option: '--row-height',
+        value: rowHeight,
+      },
+    ],
+  };
+
+  // Validate orientations and alignments
+  if (!ORIENTATIONS.includes(orientation)) {
+    throw new Error('Invalid orientation. Choose one of the following: ' + ORIENTATIONS.join(', '));
+  }
+
+  if (hAlign && !HORIZONTAL_ALIGNMENTS.includes(hAlign)) {
+    throw new Error('Invalid horizontal alignment. Choose one of the following: ' + HORIZONTAL_ALIGNMENTS.join(', '));
+  }
+
+  if (vAlign && !VERTICAL_ALIGNMENTS.includes(vAlign)) {
+    throw new Error('Invalid vertical orientation. Choose one of the following: ' + VERTICAL_ALIGNMENTS.join(', '));
+  }
+
+  // Ensure numeric values are positive integers
+  if (rowHeight && (isNaN(rowHeight) || !Number.isInteger(Number(rowHeight)) || Number(rowHeight) < 1)) {
+    throw new Error('--row-height must be a positive integer.');
+  }
+
+  if (columnWidth && (isNaN(columnWidth) || !Number.isInteger(Number(columnWidth)) || Number(columnWidth) < 1)) {
+    throw new Error('--column-width must be a positive integer.');
+  }
+
+  // Ensure canvas width is given
+  if (orientation === '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)
+  ) {
+    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) {
+    throw new Error(`--canvas-width must be greater than 2 gaps or ${gap * 2}px.`);
+  }
+
+  // Ensure canvas height is given
+  if (orientation === '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)
+  ) {
+    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) {
+    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) {
+    if (value) {
+      displayWarningMessage(`"${option}" option is ignored due to ${orientation} orientation.`);
+    }
+  }
+
+  const params = {
+    rowHeight: Number(rowHeight) || null,
+    columnWidth: Number(columnWidth) || null,
+    canvasHeight: Number(canvasHeight) || null,
+    canvasWidth: Number(canvasWidth) || null,
+    orientation,
+    hAlign,
+    vAlign,
+  };
+
+  return params;
+};
+
+export const validateAspectOptions = (sharedOptions, squareOptions) => {
+  // 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.');
+  }
+
+  // Ensure aspect ratio is valid
+  const parsedAspectRatio = parseAspectRatio(aspectRatio);
+  if (!parsedAspectRatio) {
+    throw new Error('--aspect-ratio must be a valid ratio. Examples: 16/9, 2:3, 1x2, 1.77');
+  }
+
+  if (imageWidth && (isNaN(imageWidth) || !Number.isInteger(Number(imageWidth)) || Number(imageWidth) < 1)) {
+    throw new Error('--image-width must be a positive integer.');
+  }
+
+  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 = {
+    aspectRatio: parsedAspectRatio,
+    imageWidth: Number(imageWidth) || null,
+    columns: Number(columns),
+    caption,
+    captionColor,
+    maxCaptionSize,
+  };
+
+  return formattedParams;
+};

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

@@ -0,0 +1,148 @@
+import path from 'node:path';
+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) => {
+  // Destructure params
+  const { aspectRatio, imageWidth, columns, gap, canvasColor, caption, captionColor, maxCaptionSize } = validatedParams;
+
+  // Calculate width if needed, and height from aspect ratio
+  const width = imageWidth || (await getSmallestImageDimensions(images)).smallestWidth;
+  const height = Math.floor(width / aspectRatio);
+
+  // resize images to match width and height
+  const resizedImages = images.map((image) => {
+    return image.resize({
+      width,
+      height,
+      fit: 'fill',
+    });
+  });
+
+  // Get filenames if needed
+  let filenames = null;
+  if (caption) {
+    filenames = files.map((file) => path.basename(file));
+  }
+
+  // Lay images in a grid
+  const gridParams = {
+    images: resizedImages,
+    width,
+    height,
+    columns,
+    gap,
+    canvasColor,
+    filenames,
+    caption,
+    captionColor,
+    maxCaptionSize,
+  };
+
+  return await layImagesInGrid(gridParams);
+};
+
+const layImagesInGrid = async (opts) => {
+  // Destructure params
+  const { images, width, height, columns, gap, canvasColor, filenames, 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',
+  });
+
+  // Set constant
+  const CAPTION_HEIGHT_TO_CANVAS_WIDTH_RATIO = 0.04;
+
+  // Calculate number of rows
+  const rows = Math.ceil(images.length / columns);
+
+  // Calculate canvas width and caption height
+  const canvasWidth = width * columns + (columns + 1) * gap;
+  const captionHeight = Math.floor(canvasWidth * CAPTION_HEIGHT_TO_CANVAS_WIDTH_RATIO);
+
+  // Calculate canvas height
+  const minimumCanvasHeight = height * rows + (rows + 1) * gap;
+  const canvasHeight = caption ? minimumCanvasHeight + rows * captionHeight : minimumCanvasHeight;
+
+  // Calculate font size if needed
+  let fontSize = null;
+  if (caption) {
+    const longestFilename = filenames.reduce((longest, current) => {
+      return current.length > longest.length ? current : longest;
+    });
+
+    fontSize = await getFontSize({
+      text: longestFilename,
+      maxWidth: width,
+      maxHeight: captionHeight,
+      initialFontSize: maxCaptionSize,
+    });
+  }
+
+  // Create canvas
+  const canvas = sharp({
+    create: {
+      width: canvasWidth,
+      height: canvasHeight,
+      channels: 4,
+      background: canvasColor,
+    },
+  });
+
+  // Collect composites
+  const composites = [];
+
+  let x = gap;
+  let y = gap;
+
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < columns; col++) {
+      const index = row * columns + col;
+      if (index >= images.length) break;
+
+      const image = images[index];
+
+      composites.push({
+        input: await image.toBuffer(),
+        left: x,
+        top: y,
+      });
+
+      // Add caption if required
+      if (caption) {
+        // Create text
+        const svgBuffer = createSvgTextBuffer({
+          text: filenames[index],
+          maxWidth: width,
+          maxHeight: captionHeight,
+          fontSize,
+          fill: captionColor,
+        });
+
+        // Add text to composites
+        composites.push({
+          input: svgBuffer,
+          left: x,
+          top: y + height,
+        });
+      }
+
+      // Update coordinates
+      x += width + gap;
+
+      // Update progress bar
+      progressBar.increment();
+    }
+
+    // Update coordinates
+    y += caption ? height + gap + captionHeight : height + gap;
+    x = gap;
+  }
+
+  // Create final grid
+  canvas.composite(composites);
+  return canvas;
+};

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

@@ -0,0 +1,147 @@
+import sharp from 'sharp';
+import { 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;
+
+  // 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',
+  });
+
+  // Rescale images to match rowHeight
+  const scaledImages = await scaleImages(images, { height: rowHeight });
+
+  // Split images into rows, then calculate canvasHeight
+  const rows = await splitIntoRows(scaledImages, canvasWidth, gap, hAlign);
+  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);
+};
+
+const createMasonryLayout = async (rows, rowHeight, canvasWidth, canvasHeight, canvasColor, gap, hAlign) => {
+  const canvas = sharp({
+    create: {
+      width: canvasWidth,
+      height: canvasHeight,
+      channels: 4,
+      background: canvasColor,
+    },
+  });
+
+  const composites = [];
+
+  let currentWidth = gap;
+  let x = gap;
+  let y = gap;
+
+  for (const row of rows) {
+    const rowXStart = await computeRowXOffset(row, canvasWidth, gap, hAlign);
+    x = rowXStart;
+
+    for (const im of row) {
+      const meta = await im.metadata();
+      let finalizedImage = im;
+      let finalizedMeta = meta;
+      currentWidth += meta.width + gap;
+
+      if (currentWidth >= canvasWidth) {
+        // Calculate overflow
+        const overflow = currentWidth - canvasWidth;
+
+        // Resize (crop) image to justify
+        const resizeOptions = {
+          width: meta.width - overflow,
+          height: meta.height,
+          fit: 'cover',
+        };
+
+        // Update finalized image and metadata
+        const buff = await im.resize(resizeOptions).toBuffer();
+        finalizedImage = sharp(buff);
+        finalizedMeta = await finalizedImage.metadata();
+      }
+
+      composites.push({
+        input: await finalizedImage.toBuffer(),
+        left: x,
+        top: y,
+      });
+
+      x += finalizedMeta.width + gap;
+
+      // Update progress
+      progressBar.increment();
+    }
+
+    x = gap;
+    currentWidth = gap;
+    y += rowHeight + gap;
+  }
+
+  return canvas.composite(composites);
+};
+
+const splitIntoRows = async (images, canvasWidth, gap, hAlign) => {
+  const rows = [];
+  let currentRow = [];
+  let currentWidth = gap; // initial leading gap
+
+  for (const im of images) {
+    const meta = await im.metadata();
+    const nextWidth = currentWidth + meta.width + gap;
+
+    if (hAlign === 'justified') {
+      // Greedy: always push image, fix overflow later
+      currentRow.push(im);
+      currentWidth = nextWidth;
+
+      if (currentWidth + gap >= canvasWidth) {
+        rows.push(currentRow.slice());
+        currentRow.length = 0;
+        currentWidth = gap;
+      }
+    } else {
+      // Non-greedy: break BEFORE adding image that doesn't fit
+      if (nextWidth > canvasWidth && currentRow.length > 0) {
+        rows.push(currentRow.slice());
+        currentRow = [];
+        currentWidth = gap;
+      }
+
+      // Add the image (may be first in a new row)
+      currentRow.push(im);
+      currentWidth += meta.width + gap;
+    }
+  }
+
+  if (currentRow.length > 0) {
+    rows.push(currentRow);
+  }
+
+  return rows;
+};
+
+const computeRowXOffset = async (row, canvasWidth, gap, hAlign) => {
+  // Calculate total row width
+  let totalWidth = gap * (row.length + 1);
+  for (const im of row) {
+    const meta = await im.metadata();
+    totalWidth += meta.width;
+  }
+
+  // Get x offset
+  if (hAlign === 'left' || hAlign === 'justified') {
+    return gap;
+  }
+  if (hAlign === 'right') {
+    return canvasWidth - totalWidth + gap;
+  }
+  if (hAlign === 'center') {
+    const canvasGap = gap * 2;
+    return Math.floor((canvasWidth + canvasGap - totalWidth) / 2);
+  }
+};

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

@@ -0,0 +1,57 @@
+import { calculateAvgWidth, calculateAvgHeight } from '../merge-utils.js';
+import { buildHorizontalMasonry } from './horizontal.js';
+import { buildVerticalMasonry } from './vertical.js';
+
+const ORIENTATION_DEFAULTS = {
+  horizontal: {
+    needed: ['canvasWidth', 'rowHeight', 'hAlign'],
+    defaults: {
+      rowHeight: calculateAvgHeight,
+      hAlign: () => 'justified',
+    },
+  },
+  vertical: {
+    needed: ['canvasHeight', 'columnWidth', 'vAlign'],
+    defaults: {
+      columnWidth: calculateAvgWidth,
+      vAlign: () => 'justified',
+    },
+  },
+};
+
+export const masonryMerge = async (images, opts) => {
+  const { orientation } = opts;
+  const params = await getOrientationSpecificParams(images, opts);
+
+  return await generateGrid(orientation, images, params);
+};
+
+const getOrientationSpecificParams = async (images, currentParams) => {
+  const { orientation, gap, canvasColor } = currentParams;
+  const config = ORIENTATION_DEFAULTS[orientation];
+
+  const output = { gap, canvasColor };
+
+  for (const key of config.needed) {
+    if (currentParams[key] != null) {
+      output[key] = currentParams[key];
+    }
+  }
+
+  // Assign static defaults
+  for (const [key, getter] of Object.entries(config.defaults)) {
+    if (output[key] == null) {
+      output[key] = await getter(images);
+    }
+  }
+
+  return output;
+};
+
+const generateGrid = async (orientation, images, params) => {
+  if (orientation === 'horizontal') {
+    return await buildHorizontalMasonry(images, params);
+  } else {
+    return buildVerticalMasonry(images, params);
+  }
+};