@mapka/sprites-generate 0.4.1

package/src/generate.ts

@@ -0,0 +1,336 @@
+import ShelfPack from "@mapka/shelf-pack";
+import mapnik from "@mapnik/mapnik";
+import { extractSvgMetadata } from "./metadata.js";
+import type { DataLayout, DataSvgImage, ImgLayout, SvgImage } from "./types.js";
+import type { Metadata } from "./validate.js";
+
+interface Item {
+  height: number;
+  width: number;
+  id: string;
+}
+
+function heightAscThanNameComparator(a: Item, b: Item) {
+  return b.height - a.height || (a.id === b.id ? 0 : a.id < b.id ? -1 : 1);
+}
+
+function isNotNull<T>(value: T | null): value is T {
+  return value !== null
+}
+
+export interface Img {
+  svg: Buffer;
+  id: string;
+}
+
+export interface GenerateLayoutOptions {
+  /**
+   * Overrides the max_size in mapnik
+   */
+  maxIconSize?: number;
+  /**
+   * If set, filters out icons that mapnik says are too big
+   */
+  removeOversizedIcons?: boolean;
+
+  /** 
+   * If set, filters out icons that have no height or width attribute set
+   * @default true
+   */
+  removeSizeMissingIcons?: boolean;
+
+  /**
+   * If false, omits stretch and placeholder metadata (`content`, `stretchX`, `stretchY`, `placeholder`) in {@link DataLayout}
+   * @default true
+   */
+  extractMetadata?: boolean;
+  /**
+   * If true, generate {@link DataLayout} as first argument to callback and {@link ImgLayout} as the second argument; if false, generate only {@link ImgLayout} as the first argument to the callback function
+   */
+  format: boolean;
+  pixelRatio: number;
+  imgs: Img[];
+}
+
+export type LayoutResult<T extends GenerateLayoutOptions> = T["format"] extends true
+  ? DataLayout
+  : ImgLayout;
+
+
+const oversizedRe = /image created from svg must be \d+ pixels or fewer on each side/;
+const emptyRe = /image created from svg must have a width and height greater (then|than) zero/;
+
+type NotPackedShelfPacked<T extends {x: number, y: number}> = Omit<T, 'x' | 'y'>;
+
+/**
+ * Create an image from an svg data
+ */
+function createImage(
+  img: Img,
+  options: GenerateLayoutOptions,
+): Promise<NotPackedShelfPacked<SvgImage> | NotPackedShelfPacked<DataSvgImage> | null> {
+  const { svg, id } = img;
+  const {
+    pixelRatio,
+    maxIconSize,
+    removeOversizedIcons,
+    removeSizeMissingIcons,
+    extractMetadata,
+    format
+  } = options;
+
+  const svgImageOptions: { scale: number, max_size?: number } = {
+    scale: pixelRatio,
+  };
+  if (typeof maxIconSize === 'number') {
+    svgImageOptions.max_size = maxIconSize;
+  }
+
+  return new Promise<NotPackedShelfPacked<SvgImage> | NotPackedShelfPacked<DataSvgImage> | null>((resolve, reject) => {
+    mapnik.Image.fromSVGBytes(
+      svg,
+      svgImageOptions,
+      (err, image) => {
+        if (err) {
+          // Produce null result if image was too big and removeOversizedIcons is true
+          // Check for specific error message to avoid false positive
+          if (
+            removeOversizedIcons && err.message.match(oversizedRe)) {
+            return resolve(null);
+          }
+          // Produce a null result if no width or height attributes and removeSizeMissingIcons is true
+          // The error message from mapnik has a typo "then"; account for potential future fix to "than".
+          if (removeSizeMissingIcons && err.message.match(emptyRe)) {
+            return resolve(null);
+          }
+          // Any other error is a real error
+          return reject(err);
+        }
+        const height = image.height();
+        const width = image.width();
+
+        if (!width || !height) {
+          return resolve(null);
+        }
+
+        // For the data layout JSON (when options.format is true), extract stretch and placeholder metadata if present
+        // In addition to mapka-stretch and mapka-text-placeholder, also check for mapbox-stretch and mapbox-text-placeholder
+        if (format && extractMetadata) {
+          if (
+            svg.includes("mapbox-stretch") ||
+            svg.includes("mapbox-text-placeholder") ||
+            svg.includes("mapka-stretch") ||
+            svg.includes("mapka-text-placeholder")
+          ) {
+            extractSvgMetadata({ svg, pixelRatio }, (err: Error | null, metadata: Metadata) => {
+              if (err) return reject(err);
+
+              return resolve({
+                svg,
+                id,
+                width,
+                height,
+                buffer: image,
+                ...metadata,
+              });
+            });
+            return;
+          }
+        }
+        return resolve({
+          svg,
+          id,
+          width,
+          height,
+          buffer: image,
+        });
+      },
+    );
+  });
+}
+
+async function createImages(options: GenerateLayoutOptions) {
+  const images = await Promise.all(options.imgs.map((img) => createImage(img, options)));
+
+  // Remove nulls because of removeSizeMissingIcons, removeOversizedIcons
+  const nonNullImages = images.filter(isNotNull);
+
+  // Sort images by height ascending and by id ascending
+  const sortedImages = nonNullImages.toSorted(heightAscThanNameComparator);
+
+  return sortedImages;
+}
+
+function normalizeOptions<T extends GenerateLayoutOptions>(options: T): T {
+  const {
+    extractMetadata = true,
+    removeSizeMissingIcons = true,
+    pixelRatio,
+    imgs = []
+  } = options;
+
+  if (!Array.isArray(imgs)) {
+    throw new Error("imgs must be an array");
+  }
+  if (!Number.isInteger(pixelRatio)) {
+    throw new Error("pixelRatio must be a number");
+  }
+
+  return {
+    ...options,
+    pixelRatio,
+    extractMetadata,
+    removeSizeMissingIcons,
+    imgs,
+  };
+}
+
+/**
+ * Pack a list of images with width and height into a sprite layout.
+ * options object with the following keys:
+ * Generated Layout Object with sprite contents
+ */
+export async function generateLayout<T extends GenerateLayoutOptions>(
+  options: T,
+): Promise<LayoutResult<T>> {
+  const normalizedOptions = normalizeOptions(options);
+
+  // Create images from all svg images using same options
+  const allImages = await createImages(normalizedOptions);
+
+  /**
+   * Create a ShelfPack instance with autoResize = true
+   * Pack all images into the sprite
+   * Packing will mutate the images in place and add `x` and `y` properties
+   */
+  const sprite = new ShelfPack(1, 1, { autoResize: true });
+  sprite.pack(allImages, {
+    inPlace: true
+  });
+
+  if (normalizedOptions.format === false) {
+    return {
+      width: sprite.w,
+      height: sprite.h,
+      items: allImages as SvgImage[]
+    } as LayoutResult<T>;
+  }
+
+  if (normalizedOptions.format === true) {
+    const dataLayout: DataLayout = {};
+    (allImages as DataSvgImage[]).forEach((item) => {
+      dataLayout[item.id] = {
+        width: item.width,
+        height: item.height,
+        x: item.x,
+        y: item.y,
+        pixelRatio: options.pixelRatio
+      };
+
+      if (item.placeholder) {
+        dataLayout[item.id].placeholder = item.placeholder;
+      }
+      if (item.content) {
+        dataLayout[item.id].content = item.content;
+      }
+      if (item.stretchX) {
+        dataLayout[item.id].stretchX = item.stretchX;
+      }
+      if (item.stretchY) {
+        dataLayout[item.id].stretchY = item.stretchY;
+      }
+    });
+    return dataLayout as LayoutResult<T>;
+  }
+
+  throw new Error("Invalid format");
+}
+
+/**
+ * Same as generateLayout but can be used to dedupe identical SVGs
+ * and still preserve the reference.
+ *
+ * For example if `A.svg` and `B.svg` are identical, a single icon
+ * will be in the sprite image and both A and B will reference the same image
+ *
+ */
+export async function generateLayoutUnique<T extends GenerateLayoutOptions>(
+  options: T,
+): Promise<LayoutResult<T>> {
+  const normalizedOptions = normalizeOptions(options);
+
+  /* The svg signature of each item */
+  const svgPerItemId: Record<string, string> = {};
+
+  /* The items for each SVG signature */
+  const itemIdsPerSvg: Record<string, string[]> = {};
+
+  normalizedOptions.imgs.forEach((item) => {
+    var svg = item.svg.toString("base64");
+
+    svgPerItemId[item.id] = svg;
+
+    if (svg in itemIdsPerSvg) {
+      itemIdsPerSvg[svg].push(item.id);
+    } else {
+      itemIdsPerSvg[svg] = [item.id];
+    }
+  });
+
+  /* Only keep 1 item per svg signature for packing */
+  normalizedOptions.imgs = normalizedOptions.imgs.filter((item) => {
+    var svg = svgPerItemId[item.id];
+    return item.id === itemIdsPerSvg[svg][0];
+  });
+
+  const allImages = await createImages(normalizedOptions);
+
+  /**
+   * Create a ShelfPack instance with autoResize = true
+   * Pack all images into the sprite
+   * Packing will mutate the images in place and add `x` and `y` properties
+   */
+  const sprite = new ShelfPack(1, 1, { autoResize: true });
+  sprite.pack(allImages, {
+    inPlace: true
+  });
+
+  if (normalizedOptions.format) {
+    const dataLayout: DataLayout = {};
+    (allImages as DataSvgImage[]).forEach((item) => {
+      const svg = svgPerItemId[item.id];
+      const itemIdsToUpdate = itemIdsPerSvg[svg];
+
+      itemIdsToUpdate.forEach((itemIdToUpdate) => {
+        dataLayout[itemIdToUpdate] = {
+          width: item.width,
+          height: item.height,
+          x: item.x,
+          y: item.y,
+          pixelRatio: options.pixelRatio
+        };
+
+        if (item.placeholder) {
+          dataLayout[itemIdToUpdate].placeholder = item.placeholder;
+        }
+        if (item.content) {
+          dataLayout[itemIdToUpdate].content = item.content;
+        }
+        if (item.stretchX) {
+          dataLayout[itemIdToUpdate].stretchX = item.stretchX;
+        }
+        if (item.stretchY) {
+          dataLayout[itemIdToUpdate].stretchY = item.stretchY;
+        }
+      });
+    });
+    return dataLayout as LayoutResult<T>;
+  }
+
+  return {
+    width: sprite.w,
+    height: sprite.h,
+    items: allImages as SvgImage[]
+  } as LayoutResult<T>;
+}
+

package/src/image.ts

@@ -0,0 +1,81 @@
+import type { Buffer } from "node:buffer";
+import mapnik from "@mapnik/mapnik";
+import type { ImgLayout } from "./types.js";
+
+const emptyPNG = new mapnik.Image(1, 1).encodeSync("png");
+
+/**
+ * Generate a PNG image with positioned icons on a sprite.
+ */
+export function generateImage(layout: ImgLayout): Promise<Buffer> {
+  if (typeof layout !== "object") {
+    throw new Error("layout must be an object");
+  }
+
+  if (!layout.items.length) return Promise.resolve(emptyPNG);
+
+  const {
+    width,
+    height,
+    items,
+  } = layout;
+
+  return new Promise<Buffer>((resolve, reject) => {
+    mapnik.blend(
+      items,
+      {
+        width,
+        height,
+      },
+      (err?: Error | null, image?: Buffer) => {
+        if (err) return reject(err);
+        if (!image) return reject();
+
+        resolve(image);
+      },
+    );
+  });
+}
+
+interface OptimizationOptions {
+  quality?: number;
+}
+
+/**
+ * Generate a PNG image with positioned icons on a sprite.
+ *
+ */
+export function generateOptimizedImage(layout: ImgLayout, {quality = 128}: OptimizationOptions): Promise<Buffer> {
+  if (typeof layout !== "object") {
+    throw new Error("layout must be an object");
+  }
+
+  if (!layout.items.length) return Promise.resolve(emptyPNG);
+
+  const {
+    width,
+    height,
+    items,
+  } = layout;
+  
+
+    return new Promise<Buffer>((resolve, reject) => {
+    mapnik.blend(
+      items,
+      {
+        format: "png",
+        mode: "hextree",
+        quality,
+        width,
+        height,
+      },
+      (err?: Error | null, image?: Buffer) => {
+        if (err) return reject(err);
+        if (!image) return reject();
+
+        resolve(image);
+      },
+    );
+  });
+
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export {generateLayout, generateLayoutUnique} from './generate.js';
+export {generateImage, generateOptimizedImage} from './image.js';
+
+export {extractSvgMetadata} from './metadata.js';
+export {validateMetadata} from './validate.js';

package/src/metadata.js

@@ -0,0 +1,193 @@
+import { resolvePluginConfig } from 'svgo/lib/svgo/config.js';
+import { parseSvg } from 'svgo/lib/parser.js';
+import { stringifySvg } from 'svgo/lib/stringifier.js';
+import { invokePlugins } from 'svgo/lib/svgo/plugins.js';
+import svgBoundings from 'svg-boundings';
+
+const computePathBounds = svgBoundings.path;
+
+const metadataPrefix = 'mapbox-';
+
+// Removes `style` attribute. Otherwise, transforms will not apply. 
+// Refer to https://github.com/svg/svgo/blob/a9834efa1603198ae606765292215462ae193d0d/plugins/applyTransforms.js#L55-L57
+const removeStyleAttribute = {
+    name: 'removeStyleAttribute',
+      type: 'perItem',
+  fn: (item) => {
+    if (item.hasAttr('style'))
+        item.removeAttr('style');
+    return item;
+    }
+};
+
+// Transforms `id="mapbox-*"` into `mapbox:metadata="*"` so that the `convertPathData` step
+// resolves transforms.
+const renameMapboxMetadata = {
+    name: 'renameMapboxMetadata',
+    type: 'perItem',
+    fn: function(item) {
+        if (item.hasAttr('id')) {
+            const id = item.attr('id');
+            if (id.value.startsWith(metadataPrefix)) {
+                let valueSubstr = id.value.substring(metadataPrefix.length);
+                item.removeAttr('id');
+                item.addAttr({
+                    name: 'mapbox:metadata',
+                    value: valueSubstr,
+                    prefix: '',
+                    local: 'mapbox:metadata',
+                });
+            }
+        }
+
+        return item;
+    }
+};
+
+/**
+ * Decrease accuracy of floating-point numbers
+ * in path data keeping a specified number of decimals.
+ * Smart rounds values like 2.3491 to 2.35 instead of 2.349.
+ * Doesn't apply "smartness" if the number precision fits already.
+ *
+ * Taken from svgo at https://github.com/svg/svgo/blob/72db8eb/plugins/convertPathData.js#L773
+ */
+function strongRound(value, precision) {
+    if (!precision) {
+        precision = 3;
+    }
+    const error = +Math.pow(0.1, precision).toFixed(precision);
+    if (+value.toFixed(precision) !== value) {
+        var rounded = +value.toFixed(precision - 1);
+        value = +Math.abs(rounded - value).toFixed(precision + 1) >= error ?
+            +value.toFixed(precision) :
+            rounded;
+    }
+    return value;
+}
+
+// Plugin for use with svgo that extracts metadata from paths.
+const extractMapboxMetadata = {
+    name: 'extractMapboxMetadata',
+    type: 'perItem',
+    fn: function (item, params, info) {
+        if (item.isElem('path') && item.hasAttr('mapbox:metadata') && item.hasAttr('d')) {
+            const metadata = item.attr('mapbox:metadata');
+            const bounds = computePathBounds({ d: item.attr('d').value }, true);
+
+            // Make sure that we actually have a valid bounding box.
+            if (!Number.isFinite(bounds.left) || !Number.isFinite(bounds.right) ||
+                !Number.isFinite(bounds.top) || !Number.isFinite(bounds.bottom)) {
+                return true;
+            }
+
+            // Scale bounds by pixel ratio.
+            bounds.left = strongRound(bounds.left * info.pixelRatio);
+            bounds.top = strongRound(bounds.top * info.pixelRatio);
+            bounds.right = strongRound(bounds.right * info.pixelRatio);
+            bounds.bottom = strongRound(bounds.bottom * info.pixelRatio);
+
+            if (metadata.value.startsWith('stretch-x')) {
+                (info.metadata.stretchX = info.metadata.stretchX || []).push([bounds.left, bounds.right]);
+            } else if (metadata.value.startsWith('stretch-y')) {
+                (info.metadata.stretchY = info.metadata.stretchY || []).push([bounds.top, bounds.bottom]);
+            } else if (metadata.value === 'stretch') {
+                (info.metadata.stretchX = info.metadata.stretchX || []).push([bounds.left, bounds.right]);
+                (info.metadata.stretchY = info.metadata.stretchY || []).push([bounds.top, bounds.bottom]);
+            } else if (metadata.value === 'content' || metadata.value === 'text-placeholder') {
+                const key = metadata.value === 'content' ? 'content' : 'placeholder';
+                info.metadata[key] = [bounds.left, bounds.top, bounds.right, bounds.bottom];
+            }
+        }
+
+        return true;
+    }
+};
+
+const preparePluginsConfig = [
+    {
+        name: 'cleanupIDs',
+        params: {
+            // Remove all IDs first so that `convertPathData` resolves transforms.
+            preservePrefixes: ['mapbox-']
+        }
+    },
+    renameMapboxMetadata,
+    'convertShapeToPath'
+].map(resolvePluginConfig);
+
+const collapsePluginsConfig = [
+    'convertTransform',
+    'moveGroupAttrsToElems',
+    'collapseGroups'
+].map(resolvePluginConfig);
+
+const extractPluginsConfig = [
+    removeStyleAttribute,
+    {
+        name: 'convertPathData',
+        params: {
+            // svg-boundings has trouble parsing consecutive numbers without space and without a leading
+            // zero. Therefore, we force leading zeros. Note that this option confusingly has to be set
+            // to _false_ to produce leading zeros.
+            // See https://github.com/kfitfk/svg-boundings/issues/2
+            leadingZero: false
+        }
+    },
+    extractMapboxMetadata
+].map(resolvePluginConfig);
+
+/**
+ * Parses a SVG document and extracts metadata from its shapes and paths.
+ *
+ * @param   {Object}                [img]
+ * @param   {Buffer|string}         [img.svg]             A string of the SVG.
+ * @param   {number}                [img.pixelRatio]      Ratio of a 72dpi screen pixel to the destination pixel density
+ * @param   {Function}              callback              Accepts two arguments, `err` and `metadata` Object
+ * @return  {Metadata}              metadata              An object with the extracted information.
+ */
+export function extractSvgMetadata(img, callback) {
+    try {
+        const imgSvg = Buffer.isBuffer(img.svg) ? img.svg.toString('utf-8') : img.svg;
+
+        let result = parseSvg(imgSvg);
+
+        // We'll add the metadata that we extract in the svgo plugin above to this object.
+        const info = {
+            metadata: {},
+            pixelRatio: Number.isFinite(img.pixelRatio) && img.pixelRatio || 1
+        };
+
+        let previousSVG;
+        let svg = img.svg;
+
+        try {
+            // A few initial plugins prepare the data, e.g. by moving IDs to custom attributes.
+            result = invokePlugins(result, info, preparePluginsConfig);
+
+            // We'll walk through the plugins that collapse groups until there are no changes to the output.
+            do {
+                previousSVG = svg;
+                result = invokePlugins(result, info, collapsePluginsConfig);
+                svg = stringifySvg(result).data;
+            } while (previousSVG !== svg);
+
+            // Finally, we'll run through the plugins that actually read and parse the metadata.
+            invokePlugins(result, info, extractPluginsConfig);
+        } catch (err) {
+            return callback(err);
+        }
+
+        // Sort stretches ascending.
+        for (const key of ['stretchX', 'stretchY']) {
+            if (info.metadata[key]) {
+                info.metadata[key].sort((a, b) => a[0] - b[0]);
+            }
+        }
+
+        callback(null, info.metadata);
+    } catch (err) {
+        return callback(err);
+    }
+}
+

package/src/types.ts

@@ -0,0 +1,40 @@
+import type { Image } from "@mapnik/mapnik";
+import type { Metadata } from "./validate.js";
+
+export interface SvgImage {
+  svg: Buffer;
+  id: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  buffer: Image;
+}
+
+export interface DataSvgImage extends Metadata {
+  svg: Buffer;
+  id: string;
+  width: number;
+  height: number;
+  buffer: Image;
+}
+
+export interface DataLayout {
+  [key: string]: {
+    width: number;
+    height: number;
+    x: number;
+    y: number;
+    pixelRatio: number;
+    content?: [number, number, number, number];
+    stretchX?: [number, number][];
+    stretchY?: [number, number][];
+    placeholder?: [number, number, number, number];
+  };
+}
+
+export interface ImgLayout {
+  width: number;
+  height: number;
+  items: SvgImage[];
+}