scan-raster-geom

Canonical URL:
https://alexstevovich.com/a/scan-raster-geom-nodejs

Software URL:
https://midnightcitylights.com/software/scan-raster-geom-nodejs

A lightweight utility for scanning raster images — extracting width, height, aspect ratio, orientation, and format from individual files or entire directories.
Useful for static-site generators, asset pipelines, and metadata precomputation.

Installation

npm install scan-raster-geom

Example

import scanRasterGeom from 'scan-raster-geom';

// Scan a single image file
const single = await scanRasterGeom('./assets/hero.jpg', { log: true });
console.log(single);
/*
{
    path: "hero.jpg",
    width: 1920,
    height: 1080,
    aspectRatio: "1920/1080",
    orientation: "landscape",
    format: "jpg",
    filesize: 204857
}
*/

// Scan all images in a directory (non-recursive)
const results = await scanRasterGeom('./assets/images', { log: true });
console.log(results.length, 'images found.');

// Recursive scan
const recursiveResults = await scanRasterGeom('./assets', { recursive: true });

Output Structure

{
    "path": "images/photo.jpg",
    "width": 1200,
    "height": 800,
    "aspectRatio": "1200/800",
    "orientation": "landscape",
    "format": "jpg",
    "filesize": 342131
}

Methods

scanRasterGeom(targetPath, options?)

Scans a single image or directory and returns geometric metadata.

Parameters

| Name | Type | Default | Description | | -------------------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------ | | targetPath | string | — | Path to a file or directory to scan. | | options.recursive | boolean | false | Whether to recursively traverse subdirectories. | | options.extensions | string[] | Common raster types (.jpg, .png, .webp, .tiff, etc.) | File extensions to include. | | options.log | boolean | false | Enables console output for each processed image. |

Returns

• If file: An object containing geometry metadata.
• If directory: An array of geometry metadata objects.

License

Licensed under the MIT License.