npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

sone

v1.4.0

Published

A declarative Canvas layout engine for JavaScript with advanced rich text support.

Downloads

393

Readme

Sone — A declarative Canvas layout engine for JavaScript with advanced rich text support.

Tests install size

Why Sone.js?

  • Declarative API
  • Flex Layout & CSS Grid
  • Multi-Page PDF — automatic page breaking, repeating headers & footers, margins
  • Rich Text — spans, justification, tab stops, tab leaders, text orientation (0°/90°/180°/270°)
  • Bidirectional text — RTL support for Arabic, Hebrew, and mixed LTR/RTL paragraphs
  • Hyphenation — automatic word hyphenation for 80+ languages via .hyphenate(locale)
  • Balanced line wrapping — evenly distributed line lengths via .textWrap("balance")
  • Syntax Highlighting — via sone/shiki (Shiki integration)
  • Lists, Tables, Photos, SVG Paths, QR Codes
  • Squircle, ClipGroup
  • Custom font loading — any language or script
  • Output as SVG, PDF, PNG, JPG, WebP
  • Fully Typed
  • Metadata API — access per-node layout, text segment bboxes, and .tag() labels
  • YOLO / COCO Dataset Export — generate bounding-box datasets for document layout analysis
  • All features from skia-canvas

Overview

npm install sone
import { Column, Span, sone, Text } from "sone";

function Document() {
  return Column(
    Text("Hello, ", Span("World").color("blue").weight("bold"))
      .size(44)
      .color("black"),
  )
    .padding(24)
    .bg("white");
}

// save as buffer
const buffer = await sone(Document()).jpg();

// save to file
import fs from "node:fs/promises";
await fs.writeFile("image.jpg", buffer);

More examples can be found in the test/visual directory.


Syntax Highlighting

Install Shiki as a peer dependency, then import from sone/shiki:

npm install shiki
import { Column, sone } from "sone";
import { createSoneHighlighter } from "sone/shiki";

// Pre-load themes and languages once
const highlight = await createSoneHighlighter({
  themes: ["github-dark"],
  langs: ["typescript", "javascript", "bash"],
});

// Code() returns a ColumnNode — compose it like any other node
const doc = Column(
  highlight.Code(`const greet = (name: string) => \`Hello, \${name}!\``, {
    lang: "typescript",
    theme: "github-dark",
    fontSize: 13,
    fontFamily: ["monospace"],
    lineHeight: 1.6,
  }),
).padding(24).bg("white");

await sone(doc).pdf();

CodeOptions:

| Option | Type | Default | Description | |---|---|---|---| | lang | BundledLanguage | — | Shiki language identifier. | | theme | BundledTheme | first loaded theme | Shiki theme. | | fontSize | number | 12 | Font size in pixels. | | fontFamily | string[] | ["monospace"] | Font families in priority order. | | lineHeight | number | inherited | Line height multiplier. | | paddingX | number | 12 | Horizontal padding inside the block. | | paddingY | number | 8 | Vertical padding inside the block. |


Multi-Page PDF

Pass pageHeight to enable automatic page breaking. Headers and footers repeat on every page; use a function to access per-page info.

import { Column, Row, Text, Span, sone } from "sone";

const header = Row(Text("My Report").size(10)).padding(8, 16);

const footer = ({ pageNumber, totalPages }) =>
  Row(Text(Span(`${pageNumber}`).weight("bold"), ` / ${totalPages}`).size(10))
    .padding(8, 16)
    .justifyContent("flex-end");

const content = Column(
  Text("Section 1").size(24).weight("bold"),
  Text("Lorem ipsum...").size(12).lineHeight(1.6),
  // PageBreak() forces a new page at any point
).gap(12);

const pdf = await sone(content, {
  pageHeight: 1056,          // Letter height @ 96 dpi
  header,
  footer,
  margin: { top: 16, bottom: 16 },
  lastPageHeight: "content", // trim last page to actual content
}).pdf();

Tab Stops

Align columns without a Table node using \t and .tabStops().

Text("Name\tAmount\tDate")
  .tabStops(200, 320)
  .font("GeistMono")
  .size(12)

Add .tabLeader(char) to fill the tab gap with a repeated character — dot leader (.) is the classic MS Word table-of-contents style, but any character works.

// Table of contents — dot leader
Text("Introduction\t1")
  .tabStops(360)
  .tabLeader(".")
  .size(13)

// Financial report — dash leader
Text("Revenue\t$1,200,000")
  .tabStops(300)
  .tabLeader("-")
  .size(13)

Balanced Line Wrapping

.textWrap("balance") narrows the effective line-break width so all lines end up roughly equal in length — useful for headings, pull-quotes, and card titles where a ragged last line looks awkward. The text node itself shrinks to the balanced content width, so it composes naturally inside flex containers.

// Heading — balanced lines vs. greedy default
Text("Breaking News: Scientists Discover New Species in the Amazon Rainforest")
  .font("sans-serif")
  .size(28)
  .weight("bold")
  .maxWidth(480)
  .textWrap("balance")

Hyphenation

.hyphenate(locale?) inserts typographic hyphens at valid syllable boundaries using Knuth–Liang patterns from the hyphen package (80+ languages). Install it as a dependency first:

npm install hyphen
// English (default)
Text("The internationalization of software requires typographical care.")
  .font("sans-serif")
  .size(16)
  .maxWidth(200)
  .hyphenate()         // same as .hyphenate("en")

// French
Text("Le développement international de logiciels nécessite une typographie soignée.")
  .hyphenate("fr")

// German — compound words benefit greatly
Text("Die Softwareentwicklung erfordert typografische Überlegungen.")
  .hyphenate("de")

// Hyphenation composes with textWrap balance
Text("Extraordinary accomplishments in internationalization.")
  .maxWidth(220)
  .hyphenate("en")
  .textWrap("balance")

Supported locale examples: "en" / "en-us" / "en-gb", "fr", "de", "es", "it", "pt", "nl", "ru", "pl", "sv", "da", "nb", "fi", "hu", "ro", "cs", "tr", "uk", "bg", "el", "la", and more. Pass true for English.

Text Orientation

Rotate text 0°/90°/180°/270°. At 90° and 270° the layout footprint swaps width and height so surrounding elements flow naturally.

Text("Rotated").size(16).orientation(90)

Lists

Use built-in markers or pass a Span for full typographic control. Supports nested lists.

import { List, ListItem, Span, Text } from "sone";

// Built-in disc marker
List(
  ListItem(Text("Automatic page breaking").size(12)),
  ListItem(Text("Repeating headers & footers").size(12)),
).listStyle("disc").markerGap(10).gap(8)

// Custom Span marker
List(
  ListItem(Text("Tab stops").size(12)),
  ListItem(Text("Text orientation").size(12)),
).listStyle(Span("→").color("black").weight("bold")).markerGap(10).gap(8)

// Numbered list (startIndex sets the starting number)
List(
  ListItem(Text("npm install sone").size(12)),
  ListItem(Text("Compose your node tree").size(12)),
  ListItem(Text("sone(root).pdf()").size(12)),
).listStyle(Span("{}.").color("black").weight("bold")).startIndex(1).gap(8)

// Dynamic arrow function marker — index is 0-based, full Span styling available
const labels = ["①", "②", "③"]
List(
  ListItem(Text("Install dependencies").size(12)),
  ListItem(Text("Configure the environment").size(12)),
  ListItem(Text("Run the build").size(12)),
).listStyle((index) => Span(labels[index]).color("royalblue").weight("bold")).gap(8)

Font Registration

import { Font } from 'sone';

await Font.load("NotoSansKhmer", "test/font/NotoSansKhmer.ttf");

// Load a specific weight variant
await Font.load("GeistMono", ["/path/to/GeistMono-Bold.ttf"], { weight: "bold" });

Font.has("NotoSansKhmer") // → boolean

Next.js

To make it work with Next.js, update your config file:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  serverExternalPackages: ["skia-canvas"],
  webpack: (config, options) => {
    if (options.isServer) {
      config.externals = [
        ...config.externals,
        { "skia-canvas": "commonjs skia-canvas" },
      ];
    }
    return config;
  },
};

export default nextConfig;

Philosophy

Inspired by Flutter and SwiftUI, Sone lets you focus on designing instead of calculating positions manually. Describe your layout as a tree of composable nodes — Column, Row, Text, Photo — and Sone figures out where everything goes.

Built for real-world document generation: invoices, letters, open graph images, reports, resumes, and anything that needs to look good at scale.

Just JavaScript, no preprocessors. Sone does not use JSX or HTML. JSX requires a build step and transpiler config. HTML requires a full CSS parser — and any missing feature becomes a confusing gap for users. Sone's API is plain function calls that work anywhere JavaScript runs, with no setup beyond npm install.

Flexbox for layout. Powered by yoga-layout — the same engine behind React Native. If you know CSS flexbox, you already know Sone's layout model.

Rich text as a first-class citizen. Mixed-style spans, justification, tab stops, decorations, drop shadows, and per-glyph gradients — all within a single Text() node.

Pages are just layout. pageHeight slices the same node tree into pages. Headers, footers, and page breaks are ordinary nodes. No special mode, no different API.

Performance. No browser, no Puppeteer, no CDP. Rendering goes directly through skia-canvas — a native Skia binding for Node.js. Images render in single-digit milliseconds, multi-page PDFs in tens of milliseconds.


API Reference

sone(node, config?)

The main render function. Returns an object with export methods.

sone(node: SoneNode, config?: SoneRenderConfig)
  .pdf()           // → Promise<Buffer>
  .png()           // → Promise<Buffer>
  .jpg(quality?)   // → Promise<Buffer>  quality: 0.0–1.0
  .svg()           // → Promise<Buffer>
  .webp()          // → Promise<Buffer>
  .raw()           // → Promise<Buffer>
  .canvas()        // → Promise<Canvas>
  .pages()         // → Promise<Canvas[]>  one per page

SoneRenderConfig

| Option | Type | Description | |---|---|---| | width | number | Exact canvas width. When set, margins inset content within it. | | height | number | Canvas height (auto-sized if omitted). | | background | string | Canvas background color. | | pageHeight | number | Enables multi-page output. Each page is this many pixels tall. | | header | SoneNode \| (info) => SoneNode | Repeating header on every page. | | footer | SoneNode \| (info) => SoneNode | Repeating footer on every page. | | margin | number \| { top, right, bottom, left } | Page margins in pixels. | | lastPageHeight | "uniform" \| "content" | "content" trims the last page to its actual height. Default "uniform". | | cache | Map | Image cache for repeated renders. |

SonePageInfo — passed to dynamic header/footer functions:

{ pageNumber: number, totalPages: number }

Column(...children) / Row(...children)

Flex layout containers. Column stacks children vertically, Row horizontally.

Layout methods — available on all node types:

| Method | Description | |---|---| | width(v) / height(v) | Fixed dimensions. | | minWidth(v) / maxWidth(v) | Size constraints. | | flex(v) | flex-grow shorthand. | | grow(v) / shrink(v) | flex-grow / flex-shrink. | | basis(v) | flex-basis. | | wrap(v) | flexWrap: "wrap", "nowrap", "wrap-reverse". | | gap(v) / rowGap(v) / columnGap(v) | Spacing between children. | | padding(…v) | CSS shorthand: 1–4 values. | | margin(…v) | CSS shorthand: 1–4 values. | | alignItems(v) | "flex-start" "flex-end" "center" "stretch" "baseline". | | alignSelf(v) | Self alignment override. | | alignContent(v) | Multi-line alignment. | | justifyContent(v) | "flex-start" "flex-end" "center" "space-between" "space-around" "space-evenly". | | direction(v) | "row" "column" "row-reverse" "column-reverse". | | position(v) | "relative" "absolute". | | top(v) / right(v) / bottom(v) / left(v) | Offset for absolute positioning. | | overflow(v) | "visible" "hidden". | | display(v) | "flex" "none" "contents". | | bg(v) | Background color, gradient string, or Photo node. | | borderWidth(…v) | CSS shorthand: 1–4 values (top, right, bottom, left). | | borderColor(v) | Border color. | | rounded(…v) | Border radius (CSS shorthand). | | borderSmoothing(v) | Squircle smoothing (0.0–1.0). | | shadow(…v) | CSS box-shadow string(s). | | opacity(v) | 0.0–1.0. | | blur(v) | Blur filter in pixels. | | rotate(v) | Rotation in degrees. | | scale(v) | Uniform scale, or scale(x, y). | | translateX(v) / translateY(v) | Transform offset. | | pageBreak(v) | "before" "after" "avoid". |


Grid(...children)

CSS Grid layout container. Children are auto-placed or explicitly positioned.

| Method | Description | |---|---| | columns(...v) | Column track sizes: fixed px, "auto", or "Nfr". | | rows(...v) | Row track sizes. | | autoRows(...v) | Implicit row track sizes. | | autoColumns(...v) | Implicit column track sizes. | | columnGap(v) / rowGap(v) | Gap between tracks. |

Children support explicit placement via layout methods:

| Method | Description | |---|---| | gridColumn(start, span?) | Column start index and optional span count. | | gridRow(start, span?) | Row start index and optional span count. |

Grid(
  Column(Text("Hero")).gridColumn(1, 2).gridRow(1),  // spans 2 cols
  Column(Text("Side")).gridColumn(3).gridRow(1),
  Column(Text("Footer")).gridColumn(1, 3),           // spans all 3
).columns("1fr", "1fr", "200px").columnGap(12).rowGap(12)

Text(...children)

A block of text. Children can be plain strings or Span nodes.

Text("Hello ", Span("world").color("blue").weight("bold")).size(16)

Text-specific methods (in addition to layout methods):

| Method | Description | |---|---| | size(v) | Font size in pixels. | | color(v) | Text color or gradient. | | weight(v) | Font weight: "normal" "bold" or a number. | | font(v) | Font family name(s). | | style(v) | "normal" "italic" "oblique". | | lineHeight(v) | Line height multiplier (e.g. 1.5). | | align(v) | "left" "right" "center" "justify". | | letterSpacing(v) | Letter spacing in pixels. | | wordSpacing(v) | Word spacing in pixels. | | indent(v) | First-line indent in pixels. | | tabStops(...v) | Tab stop x-positions in pixels. Use \t in content to snap. | | tabLeader(v) | Character to fill tab gaps (e.g. "." for dot leader, "-" for dash). | | autofit(v?) | Scale font size to fill available height. Combined with nowrap(), shrinks/grows to fill available width on a single line. | | orientation(v) | Rotation: 0 90 180 270. Layout footprint swaps at 90°/270°. | | underline(v?) | Underline thickness. | | lineThrough(v?) | Strikethrough thickness. | | overline(v?) | Overline thickness. | | highlight(v) | Background highlight color. | | strokeColor(v) / strokeWidth(v) | Text outline. | | dropShadow(v) | CSS text-shadow string. | | nowrap() | Disable text wrapping. | | textWrap(v) | "wrap" (default) or "balance" — balance distributes text so all lines are roughly equal in width. | | hyphenate(locale?) | Enable automatic hyphenation. Omit locale for English ("en"). Accepts BCP-47-like codes: "fr", "de", "es", "it", "pt", "nl", "ru", "pl", "sv", "da", "nb", and 70+ more. Requires the hyphen package. | | baseDir(v) | Paragraph base direction: "ltr", "rtl", or "auto" (auto-detected from first strong character). | | tag(v) | Debug label attached to the node — surfaced in the Metadata API and used as a YOLO class name. |


Span(text)

An inline styled segment within Text. Takes a single string.

Span("highlighted").color("orange").weight("bold").size(14)

Supports all text styling methods: color, size, weight, font, style, letterSpacing, wordSpacing, underline, lineThrough, overline, highlight, strokeColor, strokeWidth, dropShadow, offsetY.

Additional span-level methods:

| Method | Description | |---|---| | tag(v) | Debug label for this span — surfaced in the Metadata API and takes priority over the parent Text node tag when used as a YOLO class. | | textDir(v) | Per-span canvas direction override: "ltr" or "rtl". Overrides the paragraph baseDir. |


TextDefault(...children)

A layout container that cascades text styling to all descendant Text and Span nodes. Useful for setting document-wide defaults without repeating props on every node.

TextDefault(
  Column(
    Text("Heading").size(20).weight("bold"),
    Text("Body copy that inherits the font.").size(12),
  ).gap(8),
).font("GeistMono").color("#111")

Supports all text styling methods (same as Text) plus all layout methods.


List(...items)

A vertical list container.

| Method | Description | |---|---| | listStyle(v) | "disc" "circle" "square" "decimal" "dash" "none", a Span node, or (index: number) => Span for dynamic per-item markers (index is 0-based). | | markerGap(v) | Gap between marker and item content. Default 8. | | startIndex(v) | Starting number for numeric lists. |

Plus all layout methods.

ListItem(...children)

A single item in a List. Accepts any SoneNode children. Supports all layout methods.

List(
  ListItem(Text("First item").size(12)).alignItems("center"),
  ListItem(
    Text("Nested").size(12).weight("bold"),
    List(
      ListItem(Text("Child item").size(11)),
    ).listStyle(Span("·").color("gray")).markerGap(6),
  ),
).listStyle("disc").gap(8)

Photo(src)

Displays an image. Accepts a file path, URL, or Uint8Array.

| Method | Description | |---|---| | scaleType(v, align?) | "cover" "contain" "fill". Optional alignment: "start" "center" "end". | | flipHorizontal(v?) | Mirror horizontally. | | flipVertical(v?) | Mirror vertically. |

Plus all layout methods (width, height, rounded, etc.).


Path(d)

Draws an SVG path string.

| Method | Description | |---|---| | fill(v) | Fill color. | | fillRule(v) | "evenodd" or "nonzero". | | stroke(v) | Stroke color. | | strokeWidth(v) | Stroke width. | | strokeLineCap(v) | "butt" "round" "square". | | strokeLineJoin(v) | "bevel" "miter" "round". | | strokeDashArray(...v) | Dash pattern, e.g. strokeDashArray(5, 5). | | strokeDashOffset(v) | Dash offset. | | scalePath(v) | Scale the path geometry. |

Plus all layout methods.


ClipGroup(path, ...children)

Clips its children to an SVG path shape. The path is scaled to fit the node's layout dimensions.

ClipGroup(
  "M 0 0 L 100 0 L 100 100 Z",  // SVG path string
  Photo("./image.jpg").size(150, 150),
).size(150, 150)

Supports all layout methods plus .clipPath(v) to update the path after construction.


Table(...rows) / TableRow(...cells) / TableCell(...children)

Table layout nodes.

Table(
  TableRow(
    TableCell(Text("Name").weight("bold")),
    TableCell(Text("Score").weight("bold")),
  ),
  TableRow(
    TableCell(Text("Alice")),
    TableCell(Text("98")),
  ),
).spacing(4)
  • Table: .spacing(v) — cell spacing.
  • TableCell: .colspan(v) / .rowspan(v) — spanning.
  • All three support layout methods.

PageBreak()

Inserts an explicit page break. Only has an effect when pageHeight is set.

Column(
  SectionOne,
  PageBreak(),
  SectionTwo,
)

Font

await Font.load("MyFont", "/path/to/font.ttf")
await Font.load("MyFont", ["/path/to/bold.ttf"], { weight: "bold" })
Font.has("MyFont")   // → boolean
await Font.unload("MyFont")

Bidirectional Text (RTL)

RTL paragraphs are detected automatically from the first strong character (Unicode P2–P3 rules). You can override with .baseDir() on Text or force a per-span direction with .textDir() on Span.

import { Font, sone, Column, Text, Span } from "sone";

await Font.load("NotoSansArabic", "fonts/NotoSansArabic.ttf");
await Font.load("NotoSansHebrew", "fonts/NotoSansHebrew.ttf");

Column(
  // Auto-detected RTL (first strong char is Arabic)
  Text("مرحبا بالعالم").font("NotoSansArabic").size(32),

  // Explicit RTL override
  Text("שלום עולם").font("NotoSansHebrew").size(32).baseDir("rtl"),

  // Mixed — LTR paragraph with an RTL span
  Text(
    "Total: ",
    Span("١٢٣").font("NotoSansArabic").textDir("rtl"),
    " items",
  ).size(18),
)

| Method | Description | |---|---| | Text.baseDir(v) | "ltr" "rtl" "auto" — sets paragraph direction. "auto" uses the first strong character heuristic. Default is "auto". | | Span.textDir(v) | "ltr" "rtl" — overrides canvas direction for this span only. |


Metadata API

canvasWithMetadata() and renderWithMetadata() return a SoneMetadata tree alongside the rendered canvas. Each node carries its computed layout position, dimensions, padding, margin, and — for Text nodes — fully laid-out paragraph blocks with per-segment bounding boxes.

import { sone, Column, Text, Span } from "sone";

const { canvas, metadata } = await sone(root).canvasWithMetadata();

// metadata mirrors the node tree:
// metadata.x / .y / .width / .height  — layout position
// metadata.tag                         — value from .tag() on the node
// metadata.type                        — "text" | "photo" | "column" | …

// For text nodes, access per-segment runs:
const props = metadata.props;          // TextProps
for (const { paragraph } of props.blocks) {
  for (const line of paragraph.lines) {
    for (const segment of line.segments) {
      const r = segment.run;           // { x, y, width, height } in canvas pixels
      const spanTag = segment.props.tag;
    }
  }
}

Tags are set with .tag() on any node or span:

Column(
  Text("Title").tag("title"),
  Text("Body text").tag("content"),
  Text(
    "Revenue: ",
    Span("+22%").color("green").tag("change"),
  ).tag("row"),
)

YOLO Dataset Export

toYoloDataset() transforms a SoneMetadata tree into a YOLO bounding-box dataset. Class IDs are auto-assigned alphabetically from all .tag() labels found in the tree.

import { sone, toYoloDataset } from "sone";

const { metadata } = await sone(root).canvasWithMetadata();

const ds = toYoloDataset(metadata, {
  granularity: "segment",       // "segment" | "line" | "block" | "node"
  include: ["text", "photo"],   // "text" | "photo" | "layout"
  catchAllClass: "content",     // null = skip untagged items
});

ds.classes      // Map<string, number>  e.g. { "change": 0, "row": 1, "title": 2 }
ds.boxes        // YoloBox[]
ds.imageWidth   // derived from root metadata
ds.imageHeight

ds.toTxt()      // YOLO .txt format: "classId cx cy w h" per line (normalised [0,1])
ds.toJSON()     // { imageWidth, imageHeight, classes, boxes }

YoloExportOptions

| Option | Type | Default | Description | |---|---|---|---| | granularity | "segment" \| "line" \| "block" \| "node" | "node" | Granularity for text nodes. Non-text nodes always emit at node level. | | include | Array<"text" \| "photo" \| "layout"> | all three | Which node types to include. | | catchAllClass | string \| null | "__unlabeled__" | Class name for untagged items. null skips them. |

Granularity levels

| Value | Emits | Tag source | |---|---|---| | "segment" | One box per text run | Span.tag()Text.tag()catchAllClass | | "line" | Union of segments on a line | Text.tag()catchAllClass | | "block" | Union of lines in a paragraph | Text.tag()catchAllClass | | "node" | Full layout bbox of the node | node.tag()catchAllClass |

YoloBox

| Field | Description | |---|---| | classId | Numeric class ID | | className | Human-readable class name | | cx cy w h | Normalised center and size [0, 1] | | x y pixelWidth pixelHeight | Absolute pixel coordinates |


COCO Dataset Export

toCocoDataset() produces the same bounding boxes as toYoloDataset but in COCO JSON format — a single object with images, annotations, and categories arrays. Category and annotation IDs are 1-based. Bboxes are absolute pixels in [x, y, width, height] format.

import { sone, toCocoDataset } from "sone";

const { metadata } = await sone(root).canvasWithMetadata();

const ds = toCocoDataset(metadata, {
  granularity: "line",
  include: ["text", "photo"],
  catchAllClass: "content",
  fileName: "invoice-001.jpg",   // recorded in the images entry
  imageId: 1,                    // default: 1
  supercategory: "document",     // default: "layout"
});

// ds.images       — [{ id, file_name, width, height }]
// ds.annotations  — [{ id, image_id, category_id, bbox, area, segmentation, iscrowd }]
// ds.categories   — [{ id, name, supercategory }]

await fs.writeFile("annotations.json", JSON.stringify(ds.toJSON(), null, 2));

Additional CocoExportOptions (extends YoloExportOptions):

| Option | Type | Default | Description | |---|---|---|---| | imageId | number | 1 | Numeric ID for the image entry. | | fileName | string | "image.jpg" | File name recorded in the image entry. | | supercategory | string | "layout" | supercategory field on every category. |


Acknowledgements

Use case

  • KhmerCoders Preview (https://github.com/KhmerCoders/khmercoders-preview)

Similar Project

License

Apache-2.0

Seanghay's Optimized Nesting Engine