@morphemeris/armilla-export

Print export for armilla chart scenes: PDF documents and PNG, JPEG, and WebP images, with the chart's text embedded in real fonts. It renders the same SVG that paintSvg from @morphemeris/armilla-core draws, so every theme property reaches the file. It's Rust compiled to WASM, dual-target for Node and the browser from one API, with no system fonts, no network access, and no filesystem access beyond the package's own files.

Install

npm install @morphemeris/armilla-core @morphemeris/armilla-export

Use

import { init as initCore, layout } from '@morphemeris/armilla-core';
import { init, exportImage, exportPdf } from '@morphemeris/armilla-export';

await initCore(); // no-ops on Node; load the WASM in the browser
await init(); // the export artifact is about 1.5 MB gzipped: load it on first use

const scene = layout(chartInput, [], view, environment, { kind: 'wheel' });

const png = exportImage(scene, [], [], { format: 'png', scale: 2, dpi: 300 });
const pdf = exportPdf([scene, gridScene], [], [], { page: 'a4', title: 'Natal chart' });
// png.data / pdf.data: Uint8Array; .notes: what was substituted, e.g. a missing font

• exportImage(scene, packs, fonts, options):

  • format: 'png' | 'jpeg' | 'webp'.
  • scale: pixels per scene unit, default 1.
  • quality: JPEG only, default 90.
  • dpi: recorded in PNG and JPEG.

• exportPdf(scenes, packs, fonts, options?): one page per scene.

  • page: 'fit' (each page is its scene's size, the default), 'a4', 'letter', or { width, height } in points.
  • orientation: 'auto' by default, which turns each sheet to its scene; or 'portrait' / 'landscape'.
  • margin, title, author.

• background: every file lies on the theme's paper, as the chart is designed. Pass 'transparent' or a #rrggbb[aa] color to change that.

• packs: the glyph packs the scene was drawn with, as for paintSvg.

• Errors throw ArmillaError from @morphemeris/armilla-core (0.7.1 or later), with code, document, and path.

• Limits (LIMIT errors):

  • images up to 16,384 px on a side and 2²⁶ px in area, and at least 1 px;
  • PDF pages up to 14,400 pt on a side, where a fitted page is the scene plus its margins;
  • at most 1,000 pages.

  A scene must be at least 0.001 units on a side (SHAPE).

Fonts

The default theme's family, Inter, is built in. Other fonts are inputs: pass TrueType or OpenType files as fonts, and they take precedence over the built-in faces. The /fonts entry point ships a catalog of open-licensed faces and loads them on demand:

import { catalogFamilies, loadCatalogFonts } from '@morphemeris/armilla-export/fonts';

catalogFamilies; // [{ family: 'Inter', weights: [400, 600] }, { family: 'Outfit', … }, …]
const fonts = await loadCatalogFonts(['Lora']); // Uint8Array[]
exportPdf([scene], [], fonts);

When a font the scene names is missing, export renders with the next family in the stack and records the substitution in notes (font:Lora→Inter). It never fails over a font.

The catalog faces are subsets of the Google Fonts originals, under the SIL Open Font License 1.1; each family's license ships beside its faces in fonts/.

License

MIT. Font licenses are listed under Fonts.