logo-soup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Johann Schopplich
+
+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

@@ -0,0 +1,129 @@
+# 🍜 logo-soup
+
+> [!NOTE]
+> Inspired by [React Logo Soup](https://github.com/sanity-labs/react-logo-soup) by [Sanity](https://github.com/sanity-labs). logo-soup is a framework-agnostic Node.js port using `sharp` for server-side analysis.
+
+Logos come in all shapes – wide wordmarks, dense icons, tall monograms – and displaying them at the same CSS size makes some look huge while others nearly vanish.
+
+logo-soup analyzes SVG/PNG images with `sharp`, detects their content bounding box, measures pixel density and visual center, then normalizes dimensions so every logo feels perceptually balanced.
+
+## Installation
+
+```bash
+pnpm add logo-soup
+
+# Or run directly
+npx logo-soup ./logos
+```
+
+## CLI
+
+```bash
+logo-soup ./public/logos -o logo-metrics.json
+```
+
+Output JSON keys are filenames only (e.g. `"logo.svg"`), so consumers can prepend their own base path.
+
+```
+logo-soup <dir> [options]
+
+Options:
+  --output, -o        Output JSON file path (default: "logo-metrics.json")
+  --base-size         Base size for normalization in px (default: 48)
+  --scale-factor      Aspect ratio normalization 0-1 (default: 0.5)
+  --density-factor    Density compensation 0-1 (default: 0.5)
+  --extensions, -e    Comma-separated file extensions (default: "svg,png")
+```
+
+## Programmatic API
+
+```ts
+import { analyze, analyzeDirectory, normalize } from 'logo-soup'
+
+// Single file
+const metrics = await analyze('./logo.svg')
+if (metrics) {
+  const dimensions = normalize(metrics, { baseSize: 48 })
+  console.log(dimensions) // { width, height, offsetX, offsetY }
+}
+
+// Batch
+const results = await analyzeDirectory('./logos', { extensions: ['svg', 'png'] })
+for (const [file, metrics] of results) {
+  const dimensions = normalize(metrics)
+  console.log(file, dimensions)
+}
+```
+
+### `analyze`
+
+Analyzes a single logo image and returns its metrics, or `undefined` if no content is detected. Throws on I/O or decode errors.
+
+**Type Declaration:**
+
+```ts
+function analyze(filePath: string, options?: AnalyzeOptions): Promise<Metrics | undefined>
+
+interface AnalyzeOptions {
+  /** Maximum dimension for the resampled image used during analysis (default: 200) */
+  sampleMaxSize?: number
+  /** Minimum contrast threshold to consider a pixel as content (default: 10) */
+  contrastThreshold?: number
+}
+
+interface Metrics {
+  contentRatio: number
+  pixelDensity: number
+  visualCenterX: number
+  visualCenterY: number
+}
+```
+
+### `analyzeDirectory`
+
+Analyzes all matching images in a directory. Returns a `Map<string, Metrics>` where keys are filenames.
+
+**Type Declaration:**
+
+```ts
+function analyzeDirectory(dirPath: string, options?: AnalyzeDirectoryOptions): Promise<Map<string, Metrics>>
+
+interface AnalyzeDirectoryOptions extends AnalyzeOptions {
+  /** File extensions to include, without dots (default: ["svg", "png"]) */
+  extensions?: string[]
+}
+```
+
+### `normalize`
+
+Converts raw metrics into display dimensions using aspect ratio normalization with density compensation.
+
+**Type Declaration:**
+
+```ts
+function normalize(metrics: Metrics, options?: NormalizeOptions): NormalizedDimensions
+
+interface NormalizeOptions {
+  /** Base size in pixels (default: 48) */
+  baseSize?: number
+  /** Aspect ratio normalization factor, 0–1 (default: 0.5) */
+  scaleFactor?: number
+  /** Density compensation factor, 0–1 (default: 0.5) */
+  densityFactor?: number
+  /** Dampening exponent for density compensation (default: 0.5) */
+  densityDampening?: number
+  /** Reference density value for compensation scaling (default: 0.35) */
+  referenceDensity?: number
+}
+
+interface NormalizedDimensions {
+  width: number
+  height: number
+  offsetX: number
+  offsetY: number
+}
+```
+
+## License
+
+[MIT](./LICENSE) License © 2025-PRESENT [Johann Schopplich](https://github.com/johannschopplich)

package/bin/logo-soup.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/cli.mjs')

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,96 @@
+import { c as DENSITY_FACTOR, d as SCALE_FACTOR, i as BASE_SIZE, o as DEFAULT_EXTENSIONS, r as analyzeDirectory, t as normalize } from "./normalize-BN3StFfP.mjs";
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import process from "node:process";
+import { defineCommand, runMain } from "citty";
+import { consola } from "consola";
+
+//#region package.json
+var name = "logo-soup";
+var version = "0.1.0";
+var description = "Normalize logo dimensions for visual balance";
+
+//#endregion
+//#region src/cli.ts
+const command = defineCommand({
+	meta: {
+		name,
+		version,
+		description
+	},
+	args: {
+		"dir": {
+			type: "positional",
+			description: "Directory containing logo images",
+			required: true
+		},
+		"output": {
+			type: "string",
+			alias: "o",
+			description: "Output JSON file path",
+			default: "logo-metrics.json"
+		},
+		"base-size": {
+			type: "string",
+			description: `Base size for normalization in px (default: ${BASE_SIZE})`
+		},
+		"scale-factor": {
+			type: "string",
+			description: `Aspect ratio normalization 0-1 (default: ${SCALE_FACTOR})`
+		},
+		"density-factor": {
+			type: "string",
+			description: `Density compensation 0-1 (default: ${DENSITY_FACTOR})`
+		},
+		"extensions": {
+			type: "string",
+			alias: "e",
+			description: `Comma-separated file extensions (default: "${DEFAULT_EXTENSIONS.join(",")}")`
+		}
+	},
+	async run({ args }) {
+		const dirPath = path.resolve(args.dir);
+		try {
+			if (!(await fsp.stat(dirPath)).isDirectory()) {
+				consola.error(`Not a directory: ${dirPath}`);
+				process.exit(1);
+			}
+		} catch {
+			consola.error(`Directory not found: ${dirPath}`);
+			process.exit(1);
+		}
+		const baseSize = parseNumericArg(args["base-size"], "base-size", BASE_SIZE);
+		const scaleFactor = parseNumericArg(args["scale-factor"], "scale-factor", SCALE_FACTOR);
+		const densityFactor = parseNumericArg(args["density-factor"], "density-factor", DENSITY_FACTOR);
+		const extensions = args.extensions ? args.extensions.split(",").map((ext) => ext.trim().toLowerCase()) : DEFAULT_EXTENSIONS;
+		consola.start(`Analyzing logos in ${dirPath}`);
+		const metricsMap = await analyzeDirectory(dirPath, { extensions });
+		const results = {};
+		for (const [file, metrics] of metricsMap) {
+			const dimensions = normalize(metrics, {
+				baseSize,
+				scaleFactor,
+				densityFactor
+			});
+			results[file] = dimensions;
+			consola.log(`  ${file} → ${dimensions.width}×${dimensions.height}px`);
+		}
+		const outputPath = path.resolve(args.output);
+		await fsp.mkdir(path.dirname(outputPath), { recursive: true });
+		await fsp.writeFile(outputPath, `${JSON.stringify(results, null, 2)}\n`);
+		consola.success(`Wrote ${Object.keys(results).length} entries to ${outputPath}`);
+	}
+});
+function parseNumericArg(value, name, fallback) {
+	if (value === void 0) return fallback;
+	const parsed = Number(value);
+	if (Number.isNaN(parsed)) {
+		consola.error(`Invalid value for --${name}: "${value}" (expected a number)`);
+		process.exit(1);
+	}
+	return parsed;
+}
+runMain(command);
+
+//#endregion
+export {  };

package/dist/index.d.mts

@@ -0,0 +1,73 @@
+//#region src/types.d.ts
+interface Metrics {
+  contentRatio: number;
+  pixelDensity: number;
+  visualCenterX: number;
+  visualCenterY: number;
+}
+interface NormalizedDimensions {
+  width: number;
+  height: number;
+  offsetX: number;
+  offsetY: number;
+}
+interface AnalyzeOptions {
+  /** Maximum dimension for the resampled image used during analysis. */
+  sampleMaxSize?: number;
+  /** Minimum contrast threshold to consider a pixel as content. */
+  contrastThreshold?: number;
+}
+interface NormalizeOptions {
+  /** Base size in pixels for the normalized output. */
+  baseSize?: number;
+  /** Aspect ratio normalization factor (0–1). */
+  scaleFactor?: number;
+  /** Density compensation factor (0–1). */
+  densityFactor?: number;
+  /** Dampening exponent for density compensation. */
+  densityDampening?: number;
+  /** Reference density value for compensation scaling. */
+  referenceDensity?: number;
+}
+interface AnalyzeDirectoryOptions extends AnalyzeOptions {
+  /** File extensions to include (without dots). */
+  extensions?: string[];
+}
+interface ContentBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface RGB {
+  r: number;
+  g: number;
+  b: number;
+}
+//#endregion
+//#region src/analyze.d.ts
+declare function analyze(filePath: string, options?: AnalyzeOptions): Promise<Metrics | undefined>;
+declare function analyzeDirectory(dirPath: string, options?: AnalyzeDirectoryOptions): Promise<Map<string, Metrics>>;
+//#endregion
+//#region src/defaults.d.ts
+/** Maximum dimension for the resampled image used during analysis. */
+declare const SAMPLE_MAX_SIZE: number;
+/** Minimum contrast threshold to consider a pixel as content. */
+declare const CONTRAST_THRESHOLD: number;
+/** Base size in pixels for the normalized output. */
+declare const BASE_SIZE: number;
+/** Aspect ratio normalization factor (0–1). */
+declare const SCALE_FACTOR: number;
+/** Density compensation factor (0–1). */
+declare const DENSITY_FACTOR: number;
+/** Dampening exponent for density compensation. */
+declare const DENSITY_DAMPENING: number;
+/** Reference density value for compensation scaling. */
+declare const REFERENCE_DENSITY: number;
+/** Default file extensions to scan. */
+declare const DEFAULT_EXTENSIONS: string[];
+//#endregion
+//#region src/normalize.d.ts
+declare function normalize(metrics: Metrics, options?: NormalizeOptions): NormalizedDimensions;
+//#endregion
+export { type AnalyzeDirectoryOptions, type AnalyzeOptions, BASE_SIZE, CONTRAST_THRESHOLD, type ContentBox, DEFAULT_EXTENSIONS, DENSITY_DAMPENING, DENSITY_FACTOR, type Metrics, type NormalizeOptions, type NormalizedDimensions, REFERENCE_DENSITY, type RGB, SAMPLE_MAX_SIZE, SCALE_FACTOR, analyze, analyzeDirectory, normalize };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { a as CONTRAST_THRESHOLD, c as DENSITY_FACTOR, d as SCALE_FACTOR, i as BASE_SIZE, l as REFERENCE_DENSITY, n as analyze, o as DEFAULT_EXTENSIONS, r as analyzeDirectory, s as DENSITY_DAMPENING, t as normalize, u as SAMPLE_MAX_SIZE } from "./normalize-BN3StFfP.mjs";
+
+export { BASE_SIZE, CONTRAST_THRESHOLD, DEFAULT_EXTENSIONS, DENSITY_DAMPENING, DENSITY_FACTOR, REFERENCE_DENSITY, SAMPLE_MAX_SIZE, SCALE_FACTOR, analyze, analyzeDirectory, normalize };

package/dist/normalize-BN3StFfP.mjs

@@ -0,0 +1,219 @@
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import sharp from "sharp";
+
+//#region src/defaults.ts
+/** Maximum dimension for the resampled image used during analysis. */
+const SAMPLE_MAX_SIZE = 200;
+/** Minimum contrast threshold to consider a pixel as content. */
+const CONTRAST_THRESHOLD = 10;
+/** Base size in pixels for the normalized output. */
+const BASE_SIZE = 48;
+/** Aspect ratio normalization factor (0–1). */
+const SCALE_FACTOR = .5;
+/** Density compensation factor (0–1). */
+const DENSITY_FACTOR = .5;
+/** Dampening exponent for density compensation. */
+const DENSITY_DAMPENING = .5;
+/** Reference density value for compensation scaling. */
+const REFERENCE_DENSITY = .35;
+/** Default file extensions to scan. */
+const DEFAULT_EXTENSIONS = ["svg", "png"];
+
+//#endregion
+//#region src/analyze.ts
+async function analyze(filePath, options = {}) {
+	const { sampleMaxSize = SAMPLE_MAX_SIZE, contrastThreshold = CONTRAST_THRESHOLD } = options;
+	const { pixels, width, height, alphaOnly, bg } = await extractPixels(filePath, sampleMaxSize);
+	const contentBox = detectContentBoundingBox(pixels, width, height, contrastThreshold, alphaOnly, bg);
+	if (contentBox.width === 0 || contentBox.height === 0) return;
+	const visualCenter = calculateVisualCenter(pixels, width, contentBox, contrastThreshold, alphaOnly, bg);
+	const density = measurePixelDensity(pixels, width, contentBox, contrastThreshold, alphaOnly);
+	return {
+		contentRatio: contentBox.width / contentBox.height,
+		pixelDensity: density,
+		visualCenterX: visualCenter.offsetX / contentBox.width,
+		visualCenterY: visualCenter.offsetY / contentBox.height
+	};
+}
+async function analyzeDirectory(dirPath, options = {}) {
+	const { extensions = DEFAULT_EXTENSIONS, ...analyzeOptions } = options;
+	const files = (await fsp.readdir(dirPath)).filter((fileName) => {
+		const ext = path.extname(fileName).slice(1).toLowerCase();
+		return extensions.includes(ext);
+	});
+	const results = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const absolutePath = path.resolve(dirPath, file);
+		try {
+			const metrics = await analyze(absolutePath, analyzeOptions);
+			if (metrics) results.set(file, metrics);
+		} catch {}
+	}
+	return results;
+}
+async function extractPixels(filePath, sampleMaxSize) {
+	let image = sharp(await fsp.readFile(filePath), { ...filePath.endsWith(".svg") && { density: 96 } }).ensureAlpha();
+	image = image.resize(sampleMaxSize, sampleMaxSize, {
+		fit: "inside",
+		withoutEnlargement: false
+	});
+	const { data: pixels, info } = await image.raw().toBuffer({ resolveWithObject: true });
+	const { width, height } = info;
+	let hasTransparency = false;
+	const totalPixels = width * height;
+	for (let i = 0; i < totalPixels; i++) if (pixels[i * 4 + 3] < 250) {
+		hasTransparency = true;
+		break;
+	}
+	let bg = {
+		r: 255,
+		g: 255,
+		b: 255
+	};
+	if (!hasTransparency) {
+		const corners = [
+			0,
+			(width - 1) * 4,
+			(height - 1) * width * 4,
+			((height - 1) * width + width - 1) * 4
+		];
+		let sumR = 0;
+		let sumG = 0;
+		let sumB = 0;
+		for (const offset of corners) {
+			sumR += pixels[offset];
+			sumG += pixels[offset + 1];
+			sumB += pixels[offset + 2];
+		}
+		bg = {
+			r: Math.round(sumR / 4),
+			g: Math.round(sumG / 4),
+			b: Math.round(sumB / 4)
+		};
+	}
+	return {
+		pixels,
+		width,
+		height,
+		alphaOnly: hasTransparency,
+		bg
+	};
+}
+function detectContentBoundingBox(pixels, width, height, threshold, alphaOnly, bg) {
+	let minX = width;
+	let minY = height;
+	let maxX = 0;
+	let maxY = 0;
+	for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+		const i = (y * width + x) * 4;
+		const r = pixels[i];
+		const g = pixels[i + 1];
+		const b = pixels[i + 2];
+		const a = pixels[i + 3];
+		if (isContentPixel(r, g, b, a, threshold, alphaOnly, bg)) {
+			if (x < minX) minX = x;
+			if (y < minY) minY = y;
+			if (x > maxX) maxX = x;
+			if (y > maxY) maxY = y;
+		}
+	}
+	if (minX > maxX || minY > maxY) return {
+		x: 0,
+		y: 0,
+		width,
+		height
+	};
+	return {
+		x: minX,
+		y: minY,
+		width: maxX - minX + 1,
+		height: maxY - minY + 1
+	};
+}
+function calculateVisualCenter(pixels, width, contentBox, threshold, alphaOnly, bg) {
+	let totalWeight = 0;
+	let weightedX = 0;
+	let weightedY = 0;
+	const { x: bx, y: by, width: bw, height: bh } = contentBox;
+	for (let y = 0; y < bh; y++) for (let x = 0; x < bw; x++) {
+		const i = ((by + y) * width + (bx + x)) * 4;
+		const r = pixels[i];
+		const g = pixels[i + 1];
+		const b = pixels[i + 2];
+		const a = pixels[i + 3];
+		if (!isContentPixel(r, g, b, a, threshold, alphaOnly, bg)) continue;
+		let weight;
+		if (alphaOnly) weight = a / 255;
+		else {
+			const dr = r - bg.r;
+			const dg = g - bg.g;
+			const db = b - bg.b;
+			const colorDistance = Math.sqrt(dr * dr + dg * dg + db * db);
+			weight = Math.sqrt(colorDistance) * (a / 255);
+		}
+		totalWeight += weight;
+		weightedX += (x + .5) * weight;
+		weightedY += (y + .5) * weight;
+	}
+	if (totalWeight === 0) return {
+		offsetX: 0,
+		offsetY: 0
+	};
+	return {
+		offsetX: weightedX / totalWeight - bw / 2,
+		offsetY: weightedY / totalWeight - bh / 2
+	};
+}
+function measurePixelDensity(pixels, width, contentBox, threshold, alphaOnly) {
+	const { x: bx, y: by, width: bw, height: bh } = contentBox;
+	const totalPixels = bw * bh;
+	if (totalPixels === 0) return .5;
+	let filledPixels = 0;
+	let totalOpacity = 0;
+	for (let y = 0; y < bh; y++) for (let x = 0; x < bw; x++) {
+		const i = ((by + y) * width + (bx + x)) * 4;
+		const r = pixels[i];
+		const g = pixels[i + 1];
+		const b = pixels[i + 2];
+		const a = pixels[i + 3];
+		if (isContentPixel(r, g, b, a, threshold, alphaOnly, {
+			r: 255,
+			g: 255,
+			b: 255
+		})) {
+			filledPixels++;
+			totalOpacity += a / 255;
+		}
+	}
+	if (filledPixels === 0) return 0;
+	return filledPixels / totalPixels * (totalOpacity / filledPixels);
+}
+function isContentPixel(r, g, b, a, threshold, alphaOnly, bg) {
+	if (alphaOnly) return a > threshold;
+	return a > threshold && (Math.abs(r - bg.r) > threshold || Math.abs(g - bg.g) > threshold || Math.abs(b - bg.b) > threshold);
+}
+
+//#endregion
+//#region src/normalize.ts
+function normalize(metrics, options = {}) {
+	const { baseSize = BASE_SIZE, scaleFactor = SCALE_FACTOR, densityFactor = DENSITY_FACTOR, densityDampening = DENSITY_DAMPENING, referenceDensity = REFERENCE_DENSITY } = options;
+	const ratio = metrics.contentRatio;
+	let width = ratio ** scaleFactor * baseSize;
+	let height = width / ratio;
+	if (densityFactor > 0 && metrics.pixelDensity > 0) {
+		const densityScale = (1 / (metrics.pixelDensity / referenceDensity)) ** (densityFactor * densityDampening);
+		const clampedScale = Math.max(.5, Math.min(2, densityScale));
+		width *= clampedScale;
+		height *= clampedScale;
+	}
+	return {
+		width: Math.round(width),
+		height: Math.round(height),
+		offsetX: Math.round(-(metrics.visualCenterX ?? 0) * width * 10) / 10,
+		offsetY: Math.round(-(metrics.visualCenterY ?? 0) * height * 10) / 10
+	};
+}
+
+//#endregion
+export { CONTRAST_THRESHOLD as a, DENSITY_FACTOR as c, SCALE_FACTOR as d, BASE_SIZE as i, REFERENCE_DENSITY as l, analyze as n, DEFAULT_EXTENSIONS as o, analyzeDirectory as r, DENSITY_DAMPENING as s, normalize as t, SAMPLE_MAX_SIZE as u };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "logo-soup",
+  "type": "module",
+  "version": "0.1.0",
+  "packageManager": "pnpm@10.30.0",
+  "description": "Normalize logo dimensions for visual balance",
+  "author": "Johann Schopplich <hello@johannschopplich.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/johannschopplich/logo-soup#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johannschopplich/logo-soup.git"
+  },
+  "bugs": {
+    "url": "https://github.com/johannschopplich/logo-soup/issues"
+  },
+  "keywords": [
+    "logo",
+    "image",
+    "analysis",
+    "normalization",
+    "visual-balance",
+    "sharp",
+    "svg",
+    "png"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "types": "./dist/index.d.mts",
+  "bin": {
+    "logo-soup": "bin/logo-soup.mjs"
+  },
+  "files": [
+    "bin",
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest",
+    "test:types": "tsc --noEmit",
+    "release": "bumpp"
+  },
+  "dependencies": {
+    "citty": "^0.2.1",
+    "consola": "^3.4.2",
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "^7.4.3",
+    "@types/node": "^24.10.13",
+    "bumpp": "^10.4.1",
+    "eslint": "^10.0.0",
+    "tsdown": "^0.20.3",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "@parcel/watcher",
+      "esbuild",
+      "sharp"
+    ]
+  }
+}