bdf

README

BDF

English | 日本語

BDF (Browser-specific Document Format) is a document format for previews that browsers can draw straight onto Canvas 2D. Its stable wire format is version 1.0.

Previewing a PDF, a Word file, or a CAD drawing in a browser usually means running a full office suite, or a headless browser, on the server. BDF's converters need neither: they're plain Go, and the same code also builds as WebAssembly, so it can convert inside the browser too. PDF, Office files (Word, PowerPoint, Excel, CSV, Parquet, Visio), InDesign (IDML), draw.io diagrams, CAD drawings (DXF, Jw_cad, SXF, CGM, HP-GL/2), circuit boards (Gerber, Excellon, KiCad), Illustrator, Photoshop, HTML, Markdown, EPUB, music (MML, MIDI, MusicXML, playable in the viewer), audio files (MP3, M4A, FLAC, Ogg, WAV, AIFF: their cover art, tags and lyrics, playable in the viewer) and font files all convert this way, and one renderer, running in a Web Worker, draws every one of them.

Try it — drop a file on the demo site; it converts and draws inside your browser, without being uploaded. Read the docs for why BDF exists, every format it reads, three sample server architectures, and how it's built.

Quick start

go run ./cmd/bdf generate report.pptx report.bdf   # convert
go run ./cmd/bdf ls report.bdf                     # inspect

npm ci && npm run demo                             # open it in a browser
# http://127.0.0.1:8765/examples/viewer/.out/?src=/report.bdf

Go 1.27+ and Node.js are needed to build from source; see Getting started for the rest, including converting from Go code directly.

For an npm integration, including server-converted BDF and browser conversion presets, see npm packages.

Layout

Path	Contents
*.go, converter/, encoding/, raster/, contrib/, internal/	The Go encoder/decoder, one converter package per input format, and the Parquet encoding of the tables of values a document holds
form/, vector/, text/	Filling templates of forms with data: Excel, Word and PowerPoint files with tags, PDFs with form fields, templates of pdfme, text files of the lines of continuous forms and receipts (QR codes and barcodes are image/barcode/); and writing documents as PDF files, tagged and PDF/A too, and as Markdown
packages/	The decoder, renderer, viewer surface and TinyGo-backed browser converter npm packages
examples/, site/	The demo viewer, four sample server architectures, and the site published on GitHub Pages
docs/	This documentation

See Repository layout for the full breakdown, and Building and testing for go test, browser integration tests, and regenerating fixtures.

License

MIT.

Fonts

The fonts in this repository have licenses of their own:

• STIX Two Math 2.13 b171 is embedded in the package image/formula, as the font formulas are laid out with. It is the file of the upstream release, unmodified (stipub/stixfonts, tag v2.13b171; image/formula/fonts/README.md has its SHA-256), under the SIL Open Font License 1.1. Copyright 2001-2021 The STIX Fonts Project Authors, with Reserved Font Name "TM Math". A program that imports formula holds this font.
• Bravura (music symbols, as a table in converter/internal/music/smufl) is under the SIL Open Font License 1.1. Copyright © 2015 Steinberg Media Technologies GmbH, with Reserved Font Name "Bravura".
• M PLUS 1p digit outlines are included in image/barcode for the numbers below JAN/EAN/UPC bars, under the SIL Open Font License 1.1.
• NewStroke (KiCad's stroke font, in converter/kicad) is CC0.
• DejaVu Sans subsets (in fixture, for the sample document) are under the DejaVu Fonts License.
• The test fonts (subsets of M PLUS 1p, STIX Two Math and STIX Two Text) sit beside their licenses in testdata directories.

Fonts and licenses lists them with the fonts the demo site serves.

Documentation

Index

• Constants
• Variables
• func Disassemble(data []byte) (string, error)
• func EncodeCues(c *Cues) []byte
• func EncodePathCollection(paths []*Path) []byte
• func EncodeTextIndex(runs []IndexRun) []byte
• func OpName(op byte) string
• func PlainText(runs []IndexRun) string
• type CellRef
  • func ParseCellRef(payload string) (CellRef, bool)
• type Color
  • func RGB(r, g, b uint8) Color
  • func RGBA(r, g, b, a uint8) Color
  • func (c Color) CSS() string
• type Continuous
• type Cue
• type CueSystem
• type Cues
  • func DecodeCues(data []byte) (*Cues, error)
• type DCValues
  • func SplitKeywords(s string) DCValues
  • func (v DCValues) First() string
  • func (v DCValues) MarshalJSON() ([]byte, error)
  • func (v *DCValues) UnmarshalJSON(b []byte) error
• type Document
  • func NewDocument() *Document
  • func (d *Document) AddFont(data []byte) Hash
  • func (d *Document) AddImage(data []byte) Hash
  • func (d *Document) AddObject(o *Object) (Hash, Rect)
  • func (d *Document) AddPart(typ string, data []byte) Hash
  • func (d *Document) AddPaths(paths []*Path) Hash
  • func (d *Document) AddTable(t *Table, data []byte) error
  • func (d *Document) AddTableRows(id, title string, rows *parquet.Table, view string, page int) (*Table, error)
  • func (d *Document) BuildTextIndex(v *View) (Hash, error)
  • func (d *Document) NewView(id, kind, title string) *View
  • func (d *Document) Part(h Hash) *Part
  • func (d *Document) Parts() []*Part
  • func (d *Document) SearchText() (*SearchText, error)
  • func (d *Document) Table(id string) *Table
  • func (d *Document) WriteSingle(w io.Writer) error
  • func (d *Document) WriteSplit(dir string) error
• type DublinCore
  • func (dc *DublinCore) Field(name string) *DCValues
  • func (dc DublinCore) IsZero() bool
• type Encryption
• type Font
  • func EmbeddedFont(h Hash, weight uint16, style byte) Font
  • func SystemFont(family string, weight uint16, style byte) Font
• type FontRef
• type FormatError
  • func (e *FormatError) Error() string
• type Freeze
• type Glyph
• type Hash
  • func HashOf(data []byte) Hash
  • func ParseHash(s string) (Hash, error)
  • func (h Hash) MarshalText() ([]byte, error)
  • func (h Hash) String() string
  • func (h *Hash) UnmarshalText(b []byte) error
• type ImageRef
• type IndexRun
  • func DecodeTextIndex(data []byte) ([]IndexRun, error)
• type Instr
• type KeySlot
• type Layer
• type Lock
  • func NewECDHLock(reader *ecdh.PublicKey) (*Lock, error)
  • func NewPasswordLock(password string, iter int) (*Lock, error)
• type Manifest
  • func (m *Manifest) Table(id string) *Table
• type Meta
• type NodeKind
  • func (k NodeKind) String() string
• type ObjRef
• type Object
  • func NewObject() *Object
  • func (o *Object) AddExtPath(h Hash, index uint32) PathRef
  • func (o *Object) AddFont(f Font) FontRef
  • func (o *Object) AddImage(h Hash) ImageRef
  • func (o *Object) AddObject(h Hash, bbox Rect) ObjRef
  • func (o *Object) AddPaint(p Paint) PaintRef
  • func (o *Object) AddPath(p *Path) PathRef
  • func (o *Object) Alpha(a float32) *Object
  • func (o *Object) Blend(b byte) *Object
  • func (o *Object) ClearRect(x, y, w, h float32) *Object
  • func (o *Object) ClipPath(p PathRef, rule byte) *Object
  • func (o *Object) ClipRect(x, y, w, h float32) *Object
  • func (o *Object) Dash(segments []float32, offset float32) *Object
  • func (o *Object) Deps() []Hash
  • func (o *Object) Encode() []byte
  • func (o *Object) Ext(payload []byte) *Object
  • func (o *Object) FillColor(c Color) *Object
  • func (o *Object) FillPaint(p PaintRef) *Object
  • func (o *Object) FillPath(p PathRef, rule byte) *Object
  • func (o *Object) FillPathAt(p PathRef, rule byte, x, y float32) *Object
  • func (o *Object) FillPathRun(rule byte, glyphs []Glyph) *Object
  • func (o *Object) FillRect(x, y, w, h float32) *Object
  • func (o *Object) FillText(s string, x, y, advance float32) *Object
  • func (o *Object) Filter(css string) *Object
  • func (o *Object) Font(f FontRef, size float32) *Object
  • func (o *Object) GroupBegin(alpha float32, blend byte, x, y, w, h float32) *Object
  • func (o *Object) GroupEnd() *Object
  • func (o *Object) Image(img ImageRef, x, y, w, h float32) *Object
  • func (o *Object) ImageSub(img ImageRef, sx, sy, sw, sh, dx, dy, dw, dh float32) *Object
  • func (o *Object) Line(width float32, cap, join byte, miter float32) *Object
  • func (o *Object) Link(x, y, w, h float32, url string) *Object
  • func (o *Object) Mark(kind byte, payload string) *Object
  • func (o *Object) MaskBegin(kind byte, backdrop Color, transfer []byte) *Object
  • func (o *Object) MaskEnd() *Object
  • func (o *Object) Restore() *Object
  • func (o *Object) Save() *Object
  • func (o *Object) Scale(x, y float32) *Object
  • func (o *Object) SetBBox(x, y, w, h float32) *Object
  • func (o *Object) Shadow(c Color, blur, dx, dy float32) *Object
  • func (o *Object) Smoothing(enabled bool, quality byte) *Object
  • func (o *Object) StrokeColor(c Color) *Object
  • func (o *Object) StrokePaint(p PaintRef) *Object
  • func (o *Object) StrokePath(p PathRef) *Object
  • func (o *Object) StrokeRect(x, y, w, h float32) *Object
  • func (o *Object) StrokeText(s string, x, y, advance float32) *Object
  • func (o *Object) TextStyle(align, baseline, dir byte, letterSpacing float32) *Object
  • func (o *Object) Transform(a, b, c, d, e, f float32) *Object
  • func (o *Object) Translate(x, y float32) *Object
  • func (o *Object) UpdateFont(ref FontRef, f Font)
  • func (o *Object) UpdateObject(ref ObjRef, h Hash)
  • func (o *Object) Use(obj ObjRef) *Object
  • func (o *Object) UseAt(obj ObjRef, x, y float32) *Object
• type ObjectPart
  • func DecodeObject(data []byte) (*ObjectPart, error)
  • func (o *ObjectPart) Deps() []Hash
  • func (o *ObjectPart) Instructions() ([]Instr, error)
  • func (o *ObjectPart) Walk(fn func(Instr)) error
• type Page
• type PageText
• type Paint
  • func ConicGradient(angle, x, y float32, stops ...Stop) Paint
  • func LinearGradient(x0, y0, x1, y1 float32, stops ...Stop) Paint
  • func Pattern(img ImageRef, repeat byte) Paint
  • func RadialGradient(x0, y0, r0, x1, y1, r1 float32, stops ...Stop) Paint
• type PaintRef
• type Part
• type PartEntry
• type Path
  • func DecodePathCollection(data []byte) ([]*Path, error)
  • func (p *Path) ArcTo(x1, y1, x2, y2, r float32) *Path
  • func (p *Path) Circle(x, y, r float32) *Path
  • func (p *Path) Close() *Path
  • func (p *Path) CubicTo(c1x, c1y, c2x, c2y, x, y float32) *Path
  • func (p *Path) Ellipse(x, y, rx, ry, rot, a0, a1 float32, ccw bool) *Path
  • func (p *Path) LineTo(x, y float32) *Path
  • func (p *Path) MoveTo(x, y float32) *Path
  • func (p *Path) QuadTo(cx, cy, x, y float32) *Path
  • func (p *Path) Rect(x, y, w, h float32) *Path
  • func (p *Path) RoundRect(x, y, w, h, r float32) *Path
• type PathEntry
• type PathRef
• type Play
• type PrefixMember
• type PrefixShare
  • func SharePrefixes(objs []*Object, minBytes int) ([]PrefixShare, error)
• type Reader
  • func OpenSingle(r io.ReaderAt, size int64) (*Reader, error)
  • func OpenSingleFile(path string) (*Reader, error)
  • func OpenSplit(dir string) (*Reader, error)
  • func (r *Reader) Close() error
  • func (r *Reader) Encrypted() bool
  • func (r *Reader) Entry(h Hash) (PartEntry, bool)
  • func (r *Reader) Locked() bool
  • func (r *Reader) Object(h Hash) (*ObjectPart, error)
  • func (r *Reader) Part(h Hash) ([]byte, error)
  • func (r *Reader) StoredManifest() (*Manifest, []byte)
  • func (r *Reader) StoredPart(e PartEntry) ([]byte, error)
  • func (r *Reader) Table(id string) (*Table, []byte, error)
  • func (r *Reader) ToDocument() (*Document, error)
  • func (r *Reader) Unlock(password string) error
  • func (r *Reader) UnlockECDH(priv *ecdh.PrivateKey) error
  • func (r *Reader) WriteSegment(w io.Writer, o SegmentOptions) error
  • func (r *Reader) WriteSingle(w io.Writer) error
  • func (r *Reader) WriteSplit(dir string) error
• type Rect
• type RectDef
• type Replay
  • func NewReplay(part *ObjectPart, dst *Object) *Replay
  • func (r *Replay) Emit(in Instr) (err error)
• type Run
• type SealedManifest
• type SearchText
• type Segment
  • func SegmentAt(v *View, page, size int) Segment
• type SegmentOptions
• type Split
• type Stop
• type Table
• type TableColumn
• type TextContent
  • func ExtractContent(o *ObjectPart, resolve func(Hash) *ObjectPart) (*TextContent, error)
• type TextImage
• type TextLink
• type TextNode
• type TextRun
  • func ExtractText(o *ObjectPart, resolve func(Hash) *ObjectPart) ([]TextRun, error)
• type View
  • func (v *View) AddPage(w, h float32, layers ...Layer) *Page
  • func (v *View) TileSize() float32
• type ViewText

Constants

const (
	// CipherA256GCM seals parts with AES-256-GCM; the stored bytes are the
	// 12-byte nonce followed by the ciphertext and the 16-byte tag.
	CipherA256GCM = "A256GCM"
	// KeyPassword is a key slot that a password unlocks.
	KeyPassword = "password"
	// KDFPBKDF2SHA256 derives key-encryption keys with PBKDF2-HMAC-SHA-256
	// from the password normalized to NFKC and encoded as UTF-8: full-width
	// and half-width spellings, and a letter with its marks written as one
	// character or as several, are one password.
	KDFPBKDF2SHA256 = "PBKDF2-SHA256"
	// DefaultIterations is the PBKDF2 iteration count of new password slots.
	DefaultIterations = 600_000
	// MaxIterations bounds the iteration count readers accept, so a file
	// cannot keep a reader busy for long: that of a key slot, and the sum of
	// those of the slots a reader tries.
	MaxIterations = 10_000_000

	// KeyECDH is a key slot that one reader's private key unlocks: the
	// content key is wrapped with a key agreed with ECDH between the
	// reader's public key and a key the writer makes for the document and
	// forgets (docs/spec.md §3.5).
	KeyECDH = "ecdh"
	// CurveP256 is the curve of ecdh slots (NIST P-256).
	CurveP256 = "P-256"
	// KDFHKDFSHA256 derives the key-encryption key of an ecdh slot from the
	// shared secret with HKDF-SHA-256.
	KDFHKDFSHA256 = "HKDF-SHA256"
	// MaxECDHSlots bounds the ecdh slots a reader tries: each costs a key
	// agreement.
	MaxECDHSlots = 16

	// FlagEncrypted is the single-file header flag of encrypted documents.
	FlagEncrypted = 1
)

Encryption values.

const (
	FontEmbedded byte = 0
	FontSystem   byte = 1
)

Font kinds.

const (
	StyleNormal  byte = 0
	StyleItalic  byte = 1
	StyleOblique byte = 2
)

Font styles.

const (
	ViewFixed  = "fixed"
	ViewFlow   = "flow"
	ViewSheet  = "sheet"
	ViewScroll = "scroll"
)

View kinds.

const (
	DirectionLTR = "ltr"
	DirectionRTL = "rtl"
)

Page progression directions of fixed and flow views.

const (
	RoleBackground = "background"
	RoleMaster     = "master"
	RoleHeader     = "header"
	RoleFooter     = "footer"
	RoleBody       = "body"
	RoleNotes      = "notes"
	RoleAnnotation = "annotation"
)

Layer roles.

const (
	PartObject = "obj"
	PartFont   = "font"
	PartImage  = "img"
	PartPath   = "path"
	PartIndex  = "idx"
	// PartTable is a table the document holds beside its drawing: an
	// Apache Parquet file (docs/spec.md §4.6).
	PartTable = "table"
	// PartSeq is a Standard MIDI File that a view plays (docs/spec.md §4.4).
	PartSeq = "seq"
	// PartAudio is an audio file that a view plays, as it is (docs/spec.md
	// §4.4).
	PartAudio = "audio"
	// PartTemplate describes a compiled template of forms as JSON, and
	// PartSource is the template it was compiled from (package form;
	// docs/spec.md §4.5). No view refers to them: a reader of documents
	// passes them over.
	PartTemplate = "tpl"
	PartSource   = "src"
	// PartFill is the record of a form completed from a partly filled
	// form whose values were signed: the values, and the signatures of
	// those who gave them, as JSON (package form; docs/spec.md §4.5). No
	// view refers to it.
	PartFill = "fill"
	// PartText is the print image of a form filled from a template of
	// plain text: its grid of columns and lines, and the characters of
	// each line, as JSON (package form/textpart; docs/spec.md §4). No view
	// refers to it: a reader of documents passes it over, and the writers
	// of the text modes of printers (ESC/P, ESC/POS) print from it.
	PartText = "text"
	// PartSealed is the type of the parts of an encrypted document's outer
	// manifest (docs/spec.md §3.5).
	PartSealed = "sealed"
)

Part types.

const (
	EncIdentity   = "identity"
	EncDeflateRaw = "deflate-raw"
)

Encodings.

const (
	// MaxPageSize bounds the sides of pages and of their bodies, in units:
	// the coordinates of objects are f32, which cannot tell whole units
	// apart beyond it.
	MaxPageSize = 1 << 24
	// MaxSheetEntries bounds the rows of a sheet, and its columns (Excel
	// has 1,048,576 rows).
	MaxSheetEntries = 1 << 24
	// MinEntrySize is the smallest size of a row or a column that has one
	// (0: hidden), in units.
	MinEntrySize = 1.0 / 64
	// DefaultTile is the tile size of a sheet view that states none.
	DefaultTile = 2048
	// MaxTables bounds the tables of a document, and MaxTableColumns the
	// columns of a table (docs/spec.md §4.6).
	MaxTables       = 1 << 16
	MaxTableColumns = 1 << 14
)

Limits of the numbers of a manifest. They decide how long the loops of a reader run and how much it allocates (the tiles of a region, the gridlines of a sheet, the bands of a continuous layout), so a reader checks them once, when it opens the document. What they refuse no writer has a use for.

const (
	OpSave        byte = 0x01
	OpRestore     byte = 0x02
	OpTransform   byte = 0x03
	OpTranslate   byte = 0x04
	OpScale       byte = 0x05
	OpClipPath    byte = 0x06
	OpClipRect    byte = 0x07
	OpFillColor   byte = 0x10
	OpFillPaint   byte = 0x11
	OpStrokeColor byte = 0x12
	OpStrokePaint byte = 0x13
	OpLine        byte = 0x14
	OpDash        byte = 0x15
	OpAlpha       byte = 0x16
	OpBlend       byte = 0x17
	OpShadow      byte = 0x18
	OpFilter      byte = 0x19
	OpFont        byte = 0x1A
	OpTextStyle   byte = 0x1B
	OpFillRect    byte = 0x20
	OpStrokeRect  byte = 0x21
	OpFillPath    byte = 0x22
	OpStrokePath  byte = 0x23
	OpFillPathAt  byte = 0x24
	OpFillPathRun byte = 0x25
	OpClearRect   byte = 0x26
	OpFillText    byte = 0x30
	OpStrokeText  byte = 0x31
	OpImage       byte = 0x40
	OpImageSub    byte = 0x41
	OpSmoothing   byte = 0x42
	OpUse         byte = 0x50
	OpUseAt       byte = 0x51
	OpGroupBegin  byte = 0x52
	OpGroupEnd    byte = 0x53
	OpMaskBegin   byte = 0x54
	OpMaskEnd     byte = 0x55
	OpLink        byte = 0x70
	OpMark        byte = 0x71
	OpExt         byte = 0xFF
)

Opcodes of opset 1. See docs/spec.md §7.

const (
	NonZero byte = 0
	EvenOdd byte = 1
)

Fill rules.

const (
	CapButt   byte = 0
	CapRound  byte = 1
	CapSquare byte = 2
)

Line caps.

const (
	JoinMiter byte = 0
	JoinRound byte = 1
	JoinBevel byte = 2
)

Line joins.

const (
	AlignLeft   byte = 0
	AlignRight  byte = 1
	AlignCenter byte = 2
	AlignStart  byte = 3
	AlignEnd    byte = 4
)

Text alignment.

const (
	BaselineAlphabetic  byte = 0
	BaselineTop         byte = 1
	BaselineMiddle      byte = 2
	BaselineBottom      byte = 3
	BaselineHanging     byte = 4
	BaselineIdeographic byte = 5
)

Text baseline.

const (
	DirInherit byte = 0
	DirLTR     byte = 1
	DirRTL     byte = 2
)

Text direction.

const (
	BlendSourceOver      byte = 0
	BlendMultiply        byte = 1
	BlendScreen          byte = 2
	BlendOverlay         byte = 3
	BlendDarken          byte = 4
	BlendLighten         byte = 5
	BlendColorDodge      byte = 6
	BlendColorBurn       byte = 7
	BlendHardLight       byte = 8
	BlendSoftLight       byte = 9
	BlendDifference      byte = 10
	BlendExclusion       byte = 11
	BlendHue             byte = 12
	BlendSaturation      byte = 13
	BlendColor           byte = 14
	BlendLuminosity      byte = 15
	BlendDestinationOver byte = 16
	BlendDestinationIn   byte = 17
	BlendDestinationOut  byte = 18
	BlendSourceIn        byte = 19
	BlendSourceOut       byte = 20
	BlendSourceAtop      byte = 21
	BlendDestinationAtop byte = 22
	BlendXor             byte = 23
	BlendCopy            byte = 24
	BlendLighter         byte = 25
)

Blend modes (globalCompositeOperation). See docs/spec.md appendix A.

const (
	MaskAlpha      byte = 0 // the mask's alpha
	MaskLuminosity byte = 1 // the luminosity of the mask drawn over the backdrop colour
)

Soft mask kinds (MASK_BEGIN). See docs/spec.md §7.6.

const (
	PaintLinear  byte = 0
	PaintRadial  byte = 1
	PaintConic   byte = 2
	PaintPattern byte = 3
)

Paint kinds.

const (
	RepeatBoth byte = 0
	RepeatX    byte = 1
	RepeatY    byte = 2
	NoRepeat   byte = 3
)

Pattern repeat modes.

const (
	VerbMove      byte = 0
	VerbLine      byte = 1
	VerbQuad      byte = 2
	VerbCubic     byte = 3
	VerbClose     byte = 4
	VerbRect      byte = 5
	VerbEllipse   byte = 6
	VerbArcTo     byte = 7
	VerbRoundRect byte = 8
)

Path verbs.

const (
	MarkParagraph byte = 0
	MarkLine      byte = 1
	MarkCell      byte = 2
	MarkBox       byte = 3
	MarkAltText   byte = 4
	MarkWrap      byte = 5
	MarkHeading   byte = 6  // payload: level "1"-"6"
	MarkList      byte = 7  // opens a list, closed by MarkEnd
	MarkListItem  byte = 8  // starts an item of the innermost list
	MarkTable     byte = 9  // opens a table, closed by MarkEnd
	MarkFigure    byte = 10 // payload: alternative text; opens a figure, closed by MarkEnd
	MarkEnd       byte = 11 // closes the innermost list, table or figure
	MarkLang      byte = 12 // payload: BCP 47 language of the runs that follow ("" = document default)
	MarkBarcode   byte = 13 // payload: JSON of the symbol the next drawing draws (image/barcode.Mark)
	MarkData      byte = 14 // payload: the id of the table (docs/spec.md §4.6) the open figure is the data of
)

MARK kinds (docs/spec.md §7.8).

const (
	SepNone  byte = 0
	SepSpace byte = 1
	SepBreak byte = 2
)

Separators between consecutive text runs (docs/spec.md §7.9).

const (
	// MaxUseDepth bounds how deep objects draw objects.
	MaxUseDepth = 64
	// MaxReusedInstructions bounds the instructions read from objects that
	// were walked before. What is read once is bounded by the size of the
	// document; this bounds what a document adds by drawing it again.
	MaxReusedInstructions = 1 << 27
)

Limits of walking the objects an object draws with USE. A document decides how deep objects draw objects and how often, so a small one could otherwise keep a reader busy without end (ten objects that each draw the next one ten times draw the last one 10^10 times).

const FormatVersion = 1

FormatVersion is the container format version written by this package.

const HeaderSize = 32

HeaderSize is the fixed header length of the single-file form.

const MaxManifestSize = 256 << 20

MaxManifestSize bounds both the stored and decoded manifest JSON a reader reads: a manifest states no size of its own, so a file could otherwise ask for any amount of memory.

const OpsetVersion = 1

OpsetVersion is the instruction set version written by this package.

Variables

var BlendNames = []string{
	"source-over", "multiply", "screen", "overlay", "darken", "lighten",
	"color-dodge", "color-burn", "hard-light", "soft-light", "difference",
	"exclusion", "hue", "saturation", "color", "luminosity",
	"destination-over", "destination-in", "destination-out", "source-in",
	"source-out", "source-atop", "destination-atop", "xor", "copy", "lighter",
}

BlendNames maps blend mode values to globalCompositeOperation strings.

var DCTerms = []string{
	"title", "creator", "subject", "description", "publisher", "contributor", "date", "type",
	"format", "identifier", "source", "language", "relation", "coverage", "rights", "created", "modified",
}

DCTerms lists the element names DublinCore holds, in field order.

var ErrLocked = errors.New("bdf: the document is encrypted; unlock it with its password")

ErrLocked is returned when the parts of an encrypted document are read before Reader.Unlock.

var ErrWrongKey = errors.New("bdf: the document is not sealed for this key")

ErrWrongKey is returned by Reader.UnlockECDH when no key slot opens with the private key.

var ErrWrongPassword = errors.New("bdf: wrong password")

ErrWrongPassword is returned by Reader.Unlock when no key slot opens with the password.

var Magic = [4]byte{'b', 'd', 'f', 0}

Magic is the single-file magic number: "bdf" and a NUL byte.

Functions

func Disassemble

func Disassemble(data []byte) (string, error)

Disassemble renders an Object part as human-readable text.

func EncodeCues

func EncodeCues(c *Cues) []byte

EncodeCues serializes cues as a cue index part (type "idx").

func EncodePathCollection

func EncodePathCollection(paths []*Path) []byte

EncodePathCollection encodes paths as a Path collection part (type "path").

func EncodeTextIndex

func EncodeTextIndex(runs []IndexRun) []byte

EncodeTextIndex serializes index runs as a text index part (type "idx").

func OpName

func OpName(op byte) string

OpName returns the name of an opcode as docs/spec.md §7 writes it ("FILL_PATH"), and "" for what is no opcode.

func PlainText

func PlainText(runs []IndexRun) string

PlainText joins index runs into a readable string (for tools and tests).

Types

type CellRef

type CellRef struct {
	Row, Col   int    // of the top-left cell, from 0
	Rows, Cols int    // the cells spanned, 1 or more
	Scope      string // "col" (a column header), "row" (a row header) or ""
}

CellRef is the payload of a CELL mark: a reference or a range, of a header cell or not ("B2", "A4:B4 col").

func ParseCellRef

func ParseCellRef(payload string) (CellRef, bool)

ParseCellRef reads the payload of a CELL mark.

type Color

type Color uint32

Color is a packed 0xRRGGBBAA value.

func RGB

func RGB(r, g, b uint8) Color

RGB builds an opaque color.

func RGBA

func RGBA(r, g, b, a uint8) Color

RGBA builds a color with alpha.

func (Color) CSS

func (c Color) CSS() string

CSS returns the color as a CSS color string.

type Continuous

type Continuous struct {
	Gap float32 `json:"gap"`
}

Continuous configures continuous mode of a flow view.

type Cue

type Cue struct {
	Tick   uint32
	System uint32
	X      float32
}

Cue ties a time of a view's music to a place on its pages: at Tick (in the ticks of the Standard MIDI File, or in milliseconds of an audio file) the playing position is at X on System.

type CueSystem

type CueSystem struct {
	Page       uint32 // page index in the view (0-based)
	X, Y, W, H float32
}

CueSystem is a rectangle of a page that the playing position moves through: a system of a score, or a line of the lyrics of a recording (docs/spec.md §4.4).

type Cues

type Cues struct {
	Systems []CueSystem
	Cues    []Cue // in the order of Tick
}

Cues is the content of a cue index part.

func DecodeCues

func DecodeCues(data []byte) (*Cues, error)

DecodeCues parses a cue index part.

type DCValues

type DCValues []string

DCValues holds the values of one element. In JSON a single value is a string and several values are an array of strings.

func SplitKeywords

func SplitKeywords(s string) DCValues

SplitKeywords splits a keyword list as PDF and Office documents store it into subjects. Keywords are separated by commas or semicolons (ASCII or full-width) or by the ideographic comma.

func (DCValues) First

func (v DCValues) First() string

First returns the first value, or "" when there is none.

func (DCValues) MarshalJSON

func (v DCValues) MarshalJSON() ([]byte, error)

MarshalJSON writes one value as a string and several as an array.

func (*DCValues) UnmarshalJSON

func (v *DCValues) UnmarshalJSON(b []byte) error

UnmarshalJSON accepts a string, an array of strings or null.

type Document

type Document struct {
	Meta  Meta
	Views []*View
	// Tables are the tables the document holds beside its drawing
	// (docs/spec.md §4.6): see AddTable.
	Tables []*Table

	// CompressionLevel is the flate level of the deflate-raw parts: 1
	// (BestSpeed) to 9 (BestCompression). The default, 6, is what
	// DefaultCompression names too; 9 writes files a few percent smaller
	// in four times the time of the compression.
	CompressionLevel int
	// MinCompress is the smallest decoded size that gets compressed (default 512).
	MinCompress int
	// Lock, when set, makes WriteSingle and WriteSplit encrypt the document
	// (docs/spec.md §3.5).
	Lock *Lock
	// contains filtered or unexported fields
}

Document accumulates parts and views and writes them out.

func NewDocument

func NewDocument() *Document

NewDocument creates an empty document.

func (*Document) AddFont

func (d *Document) AddFont(data []byte) Hash

AddFont stores a font file (WOFF2/TTF/OTF).

func (*Document) AddImage

func (d *Document) AddImage(data []byte) Hash

AddImage stores an image file (PNG/JPEG/WebP/AVIF/SVG).

func (*Document) AddObject

func (d *Document) AddObject(o *Object) (Hash, Rect)

AddObject encodes and stores an object, returning its hash and bbox.

func (*Document) AddPart

func (d *Document) AddPart(typ string, data []byte) Hash

AddPart stores data as a part of the given type and returns its hash. Identical content is stored once.

func (*Document) AddPaths

func (d *Document) AddPaths(paths []*Path) Hash

AddPaths stores a Path collection part.

func (*Document) AddTable

func (d *Document) AddTable(t *Table, data []byte) error

AddTable adds a table the document holds beside its drawing (docs/spec.md §4.6): t names it, and data is the Apache Parquet file of its rows, which becomes a PartTable part (t.Part is set). The id must be new to the document; the rows and the columns of t should be those of the file (AddTableRows makes both of a table in memory).

func (*Document) AddTableRows

func (d *Document) AddTableRows(id, title string, rows *parquet.Table, view string, page int) (*Table, error)

AddTableRows adds a table in memory (encoding/parquet.Table) as a table of the document, written as a Parquet file: id and title name it, and view and page say where the figure it is the data of is (page from 1; 0 for a sheet, "" for none).

func (*Document) BuildTextIndex

func (d *Document) BuildTextIndex(v *View) (Hash, error)

BuildTextIndex extracts the text of a view from the document's objects, stores it as a text index part and records it in v.TextIndex.

func (*Document) NewView

func (d *Document) NewView(id, kind, title string) *View

NewView appends a view.

func (*Document) Part

func (d *Document) Part(h Hash) *Part

Part returns a stored part.

func (*Document) Parts

func (d *Document) Parts() []*Part

Parts returns parts in insertion order.

func (*Document) SearchText

func (d *Document) SearchText() (*SearchText, error)

SearchText returns the text of the document for a search index: that of the views' text index parts (docs/spec.md §7.9), or extracted from the objects of a view without one. Pages without text are left out, and so is a scroll view when the document also has a flow view (Word, Markdown and EPUB documents may lay the same text out both ways).

The text is the document's in plain text; a document that was encrypted should not have it stored where the password does not protect it.

func (*Document) Table

func (d *Document) Table(id string) *Table

Table returns the table with an id, or nil.

func (*Document) WriteSingle

func (d *Document) WriteSingle(w io.Writer) error

WriteSingle writes the single-file form.

func (*Document) WriteSplit

func (d *Document) WriteSplit(dir string) error

WriteSplit writes the split form into dir (manifest.json and parts/<hash>).

type DublinCore

type DublinCore struct {
	Title       DCValues `json:"title,omitempty"`
	Creator     DCValues `json:"creator,omitempty"`
	Subject     DCValues `json:"subject,omitempty"`
	Description DCValues `json:"description,omitempty"`
	Publisher   DCValues `json:"publisher,omitempty"`
	Contributor DCValues `json:"contributor,omitempty"`
	Date        DCValues `json:"date,omitempty"`
	Type        DCValues `json:"type,omitempty"`
	Format      DCValues `json:"format,omitempty"`
	Identifier  DCValues `json:"identifier,omitempty"`
	Source      DCValues `json:"source,omitempty"`
	Language    DCValues `json:"language,omitempty"`
	Relation    DCValues `json:"relation,omitempty"`
	Coverage    DCValues `json:"coverage,omitempty"`
	Rights      DCValues `json:"rights,omitempty"`
	Created     DCValues `json:"created,omitempty"`
	Modified    DCValues `json:"modified,omitempty"`
}

DublinCore describes the document with the fifteen elements of the Dublin Core Metadata Element Set 1.1, plus the DCMI Terms created and modified (docs/spec.md §4.3). Every element is optional and repeatable.

func (*DublinCore) Field

func (dc *DublinCore) Field(name string) *DCValues

Field returns the values of the element with the given name (one of DCTerms), or nil for an unknown name.

func (DublinCore) IsZero

func (dc DublinCore) IsZero() bool

IsZero reports whether no element has a value.

type Encryption

type Encryption struct {
	Cipher string    `json:"cipher"`
	Keys   []KeySlot `json:"keys"`
	// Manifest is the sealed part that holds the document's manifest.
	Manifest SealedManifest `json:"manifest"`
}

Encryption is the "encryption" member of an encrypted document's outer manifest.

type Font

type Font struct {
	Kind   byte
	Hash   Hash   // embedded: font part
	Family string // CSS family list; fallback for embedded, primary for system
	Weight uint16
	Style  byte
}

Font is a font reference used by an object.

func EmbeddedFont

func EmbeddedFont(h Hash, weight uint16, style byte) Font

EmbeddedFont references a font part added with Document.AddFont.

func SystemFont

func SystemFont(family string, weight uint16, style byte) Font

SystemFont references a font by CSS family list.

type FontRef

type FontRef uint32

Local resource references inside an object.

type FormatError

type FormatError struct {
	Offset int
	Msg    string
}

FormatError reports malformed data.

func (*FormatError) Error

func (e *FormatError) Error() string

type Freeze

type Freeze struct {
	Cols int `json:"cols,omitempty"`
	Rows int `json:"rows,omitempty"`
}

Freeze describes frozen panes.

type Glyph

type Glyph struct {
	Path PathRef
	X, Y float32
}

Glyph is one placed path in a FILL_PATH_RUN.

type Hash

type Hash [16]byte

Hash identifies a part by content: the first 16 bytes of SHA-256.

func HashOf

func HashOf(data []byte) Hash

HashOf computes the part hash of data.

func ParseHash

func ParseHash(s string) (Hash, error)

ParseHash parses the hex form.

func (Hash) MarshalText

func (h Hash) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.

func (Hash) String

func (h Hash) String() string

String returns the 32-character lowercase hex form used in manifests and file names.

func (*Hash) UnmarshalText

func (h *Hash) UnmarshalText(b []byte) error

UnmarshalText implements encoding.TextUnmarshaler.

type ImageRef

type ImageRef uint32

Local resource references inside an object.

type IndexRun

type IndexRun struct {
	A, B    uint32 // page, layer (fixed/flow) or tile x, y (sheet)
	Ordinal uint32
	Sep     byte
	Text    string
}

IndexRun is one entry of a text index part.

func DecodeTextIndex

func DecodeTextIndex(data []byte) ([]IndexRun, error)

DecodeTextIndex parses a text index part.

type Instr

type Instr struct {
	Op   byte
	Args []any
}

Instr is one decoded instruction. Operands are stored in reading order; f32 operands as float32, u8/u32/varuint as uint64, string refs as string.

type KeySlot

type KeySlot struct {
	Type string `json:"type"`
	KDF  string `json:"kdf"`
	Iter int    `json:"iter,omitempty"`
	Salt []byte `json:"salt,omitempty"`
	Crv  string `json:"crv,omitempty"`
	// EPK is the writer's public key of an ecdh slot, an uncompressed point.
	EPK []byte `json:"epk,omitempty"`
	// Key is the content key wrapped with AES-KW (RFC 3394).
	Key []byte `json:"key"`
}

KeySlot holds the content key wrapped with a key derived from a password (Iter and Salt) or agreed with ECDH (Crv and EPK).

type Layer

type Layer struct {
	Role string `json:"role"`
	Obj  Hash   `json:"obj"`
}

Layer is one drawable layer of a page.

type Lock

type Lock struct {
	// contains filtered or unexported fields
}

A Lock encrypts documents: a random content key and the key slots that unlock it. Set it as Document.Lock before writing.

func NewECDHLock

func NewECDHLock(reader *ecdh.PublicKey) (*Lock, error)

NewECDHLock makes a lock with a fresh content key that only the private key of reader unlocks (a P-256 key). The key the content key is wrapped with is agreed with ECDH between reader and a key made here, which is forgotten once the lock is made: when the reader forgets its private key too, as a key pair made for one request does, nobody can open what the lock sealed any more.

func NewPasswordLock

func NewPasswordLock(password string, iter int) (*Lock, error)

NewPasswordLock makes a lock with a fresh content key that password unlocks. iter is the PBKDF2 iteration count (0: DefaultIterations).

type Manifest

type Manifest struct {
	BDF        int         `json:"bdf"`
	Encryption *Encryption `json:"encryption,omitempty"`
	Opset      int         `json:"opset,omitempty"`
	Unit       string      `json:"unit,omitempty"`
	Meta       Meta        `json:"meta,omitzero"`
	// Segment, in a segment document, names the pages it carries
	// (docs/spec.md §3.6).
	Segment *Segment `json:"segment,omitempty"`
	Views   []*View  `json:"views,omitempty"`
	// Tables are the tables the document holds beside its drawing
	// (docs/spec.md §4.6).
	Tables []*Table    `json:"tables,omitempty"`
	Parts  []PartEntry `json:"parts"`
}

Manifest is the JSON document directory.

An encrypted document stores an outer manifest that holds only BDF, Encryption and the sealed parts; the manifest it is read with is sealed (docs/spec.md §3.5).

func (*Manifest) Table

func (m *Manifest) Table(id string) *Table

Table returns the table with an id, or nil.

type Meta

type Meta struct {
	// DC describes the document itself (title, creator, dates, ...).
	DC DublinCore `json:"dc,omitzero"`
	// Source is the input format the document was converted from ("pdf", "pptx", ...).
	Source    string `json:"source,omitempty"`
	Generator string `json:"generator,omitempty"`
}

Meta holds document metadata.

type NodeKind

type NodeKind byte

NodeKind is the kind of a structure node (docs/spec.md §7.8). Leaves (paragraph, heading, caption, a cell outside a table) hold runs; containers (list, item, table, a cell inside a table, figure) hold nodes.

const (
	NodeParagraph NodeKind = iota
	NodeHeading
	NodeCaption
	NodeList
	NodeItem
	NodeTable
	NodeCell
	NodeFigure
)

Kinds of structure nodes.

func (NodeKind) String

func (k NodeKind) String() string

type ObjRef

type ObjRef uint32

Local resource references inside an object.

type Object

type Object struct {
	BBox Rect
	// contains filtered or unexported fields
}

Object builds and encodes an Object part: a display list plus its resource tables.

Coordinates are local to the object. The builder tracks the bounding box of drawing operations approximately; set BBox explicitly to override.

func NewObject

func NewObject() *Object

NewObject creates an empty object whose bbox is computed from its content.

func (*Object) AddExtPath

func (o *Object) AddExtPath(h Hash, index uint32) PathRef

AddExtPath registers a reference to path index in a Path collection part.

func (*Object) AddFont

func (o *Object) AddFont(f Font) FontRef

AddFont registers a font.

func (*Object) AddImage

func (o *Object) AddImage(h Hash) ImageRef

AddImage registers an image part reference.

func (*Object) AddObject

func (o *Object) AddObject(h Hash, bbox Rect) ObjRef

AddObject registers a child object reference. bbox is the child's bounding box, used to grow this object's bbox on USE.

func (*Object) AddPaint

func (o *Object) AddPaint(p Paint) PaintRef

AddPaint registers a gradient or pattern.

func (*Object) AddPath

func (o *Object) AddPath(p *Path) PathRef

AddPath registers an inline path and returns its reference.

func (*Object) Alpha

func (o *Object) Alpha(a float32) *Object

func (*Object) Blend

func (o *Object) Blend(b byte) *Object

func (*Object) ClearRect

func (o *Object) ClearRect(x, y, w, h float32) *Object

func (*Object) ClipPath

func (o *Object) ClipPath(p PathRef, rule byte) *Object

func (*Object) ClipRect

func (o *Object) ClipRect(x, y, w, h float32) *Object

func (*Object) Dash

func (o *Object) Dash(segments []float32, offset float32) *Object

func (*Object) Deps

func (o *Object) Deps() []Hash

Deps returns the hashes of parts this object references (fonts, images, paths, objects).

func (*Object) Encode

func (o *Object) Encode() []byte

Encode serializes the object as an Object part.

func (*Object) Ext

func (o *Object) Ext(payload []byte) *Object

func (*Object) FillColor

func (o *Object) FillColor(c Color) *Object

func (*Object) FillPaint

func (o *Object) FillPaint(p PaintRef) *Object

func (*Object) FillPath

func (o *Object) FillPath(p PathRef, rule byte) *Object

func (*Object) FillPathAt

func (o *Object) FillPathAt(p PathRef, rule byte, x, y float32) *Object

func (*Object) FillPathRun

func (o *Object) FillPathRun(rule byte, glyphs []Glyph) *Object

func (*Object) FillRect

func (o *Object) FillRect(x, y, w, h float32) *Object

func (*Object) FillText

func (o *Object) FillText(s string, x, y, advance float32) *Object

FillText draws s at (x, y). advance is the expected width in units (0 = no correction).

func (*Object) Filter

func (o *Object) Filter(css string) *Object

func (*Object) Font

func (o *Object) Font(f FontRef, size float32) *Object

func (*Object) GroupBegin

func (o *Object) GroupBegin(alpha float32, blend byte, x, y, w, h float32) *Object

func (*Object) GroupEnd

func (o *Object) GroupEnd() *Object

func (*Object) Image

func (o *Object) Image(img ImageRef, x, y, w, h float32) *Object

func (*Object) ImageSub

func (o *Object) ImageSub(img ImageRef, sx, sy, sw, sh, dx, dy, dw, dh float32) *Object

func (*Object) Line

func (o *Object) Line(width float32, cap, join byte, miter float32) *Object

func (*Object) Link

func (o *Object) Link(x, y, w, h float32, url string) *Object

func (*Object) Mark

func (o *Object) Mark(kind byte, payload string) *Object

func (*Object) MaskBegin

func (o *Object) MaskBegin(kind byte, backdrop Color, transfer []byte) *Object

MaskBegin starts drawing a soft mask for the innermost group (kind is MaskAlpha or MaskLuminosity; backdrop is the luminosity backdrop colour; transfer is nil or 256 entries mapping each mask value).

func (*Object) MaskEnd

func (o *Object) MaskEnd() *Object

MaskEnd multiplies the alpha of what the innermost group holds by the mask.

func (*Object) Restore

func (o *Object) Restore() *Object

func (*Object) Save

func (o *Object) Save() *Object

func (*Object) Scale

func (o *Object) Scale(x, y float32) *Object

func (*Object) SetBBox

func (o *Object) SetBBox(x, y, w, h float32) *Object

SetBBox fixes the bounding box instead of computing it.

func (*Object) Shadow

func (o *Object) Shadow(c Color, blur, dx, dy float32) *Object

func (*Object) Smoothing

func (o *Object) Smoothing(enabled bool, quality byte) *Object

func (*Object) StrokeColor

func (o *Object) StrokeColor(c Color) *Object

func (*Object) StrokePaint

func (o *Object) StrokePaint(p PaintRef) *Object

func (*Object) StrokePath

func (o *Object) StrokePath(p PathRef) *Object

func (*Object) StrokeRect

func (o *Object) StrokeRect(x, y, w, h float32) *Object

func (*Object) StrokeText

func (o *Object) StrokeText(s string, x, y, advance float32) *Object

func (*Object) TextStyle

func (o *Object) TextStyle(align, baseline, dir byte, letterSpacing float32) *Object

func (*Object) Transform

func (o *Object) Transform(a, b, c, d, e, f float32) *Object

func (*Object) Translate

func (o *Object) Translate(x, y float32) *Object

func (*Object) UpdateFont

func (o *Object) UpdateFont(ref FontRef, f Font)

UpdateFont replaces a registered font (used by converters that finalize font programs after the object has been built).

func (*Object) UpdateObject

func (o *Object) UpdateObject(ref ObjRef, h Hash)

UpdateObject replaces the hash of a registered child object.

func (*Object) Use

func (o *Object) Use(obj ObjRef) *Object

func (*Object) UseAt

func (o *Object) UseAt(obj ObjRef, x, y float32) *Object

type ObjectPart

type ObjectPart struct {
	Opset   uint16
	BBox    Rect
	Strings []string
	Paths   []PathEntry
	Paints  []Paint
	Fonts   []Font
	Images  []Hash
	Objects []Hash
	Ops     []byte
}

ObjectPart is a decoded Object part.

func DecodeObject

func DecodeObject(data []byte) (*ObjectPart, error)

DecodeObject parses an Object part.

func (*ObjectPart) Deps

func (o *ObjectPart) Deps() []Hash

Deps returns the hashes of the parts the object references: embedded fonts, images, path collections and objects.

func (*ObjectPart) Instructions

func (o *ObjectPart) Instructions() ([]Instr, error)

Instructions decodes the op stream into a slice.

func (*ObjectPart) Walk

func (o *ObjectPart) Walk(fn func(Instr)) error

Walk decodes the op stream, calling fn for each instruction.

type Page

type Page struct {
	W      float32  `json:"w"`
	H      float32  `json:"h"`
	Body   *RectDef `json:"body,omitempty"`
	Layers []Layer  `json:"layers"`
}

Page is a fixed-size page.

type PageText

type PageText struct {
	Page int    `json:"page,omitempty"`
	Text string `json:"text"`
}

PageText is the text of a page (numbered from 1, for links like #page=N), or of a whole sheet (Page 0).

type Paint

type Paint struct {
	Kind   byte
	Coords []float32 // linear: x0 y0 x1 y1; radial: x0 y0 r0 x1 y1 r1; conic: angle x y
	Stops  []Stop
	Image  ImageRef   // pattern only
	Repeat byte       // pattern only
	Matrix [6]float32 // pattern only
}

Paint is a gradient or pattern fill/stroke style.

func ConicGradient

func ConicGradient(angle, x, y float32, stops ...Stop) Paint

ConicGradient builds a conic gradient paint.

func LinearGradient

func LinearGradient(x0, y0, x1, y1 float32, stops ...Stop) Paint

LinearGradient builds a linear gradient paint.

func Pattern

func Pattern(img ImageRef, repeat byte) Paint

Pattern builds an image pattern paint with an identity matrix.

func RadialGradient

func RadialGradient(x0, y0, r0, x1, y1, r1 float32, stops ...Stop) Paint

RadialGradient builds a radial gradient paint.

type PaintRef

type PaintRef uint32

Local resource references inside an object.

type Part

type Part struct {
	Hash Hash
	Type string
	Data []byte
}

Part is a raw (uncompressed) part.

type PartEntry

type PartEntry struct {
	H    Hash   `json:"h"`
	T    string `json:"t"`
	Enc  string `json:"enc"`
	Len  int    `json:"len"`  // stored (possibly compressed) length
	Size int    `json:"size"` // decoded length
	Off  int64  `json:"off"`  // offset from the start of the parts region (single form)
	// Sealed names the part of the outer manifest that holds this part
	// sealed (encrypted documents only).
	Sealed Hash `json:"sealed,omitzero"`
}

PartEntry describes one part in the manifest.

type Path

type Path struct {
	Verbs []byte
	Args  []float32
}

Path is a geometric path that maps to a Path2D.

func DecodePathCollection

func DecodePathCollection(data []byte) ([]*Path, error)

DecodePathCollection decodes a Path collection part.

func (*Path) ArcTo

func (p *Path) ArcTo(x1, y1, x2, y2, r float32) *Path

ArcTo adds an arc tangent to two segments.

func (*Path) Circle

func (p *Path) Circle(x, y, r float32) *Path

Circle adds a full circle.

func (*Path) Close

func (p *Path) Close() *Path

Close closes the current sub-path.

func (*Path) CubicTo

func (p *Path) CubicTo(c1x, c1y, c2x, c2y, x, y float32) *Path

CubicTo adds a cubic bezier.

func (*Path) Ellipse

func (p *Path) Ellipse(x, y, rx, ry, rot, a0, a1 float32, ccw bool) *Path

Ellipse adds an elliptical arc (ctx.ellipse semantics, ccw as 0/1).

func (*Path) LineTo

func (p *Path) LineTo(x, y float32) *Path

LineTo adds a straight segment.

func (*Path) MoveTo

func (p *Path) MoveTo(x, y float32) *Path

MoveTo starts a new sub-path.

func (*Path) QuadTo

func (p *Path) QuadTo(cx, cy, x, y float32) *Path

QuadTo adds a quadratic bezier.

func (*Path) Rect

func (p *Path) Rect(x, y, w, h float32) *Path

Rect adds a rectangle sub-path.

func (*Path) RoundRect

func (p *Path) RoundRect(x, y, w, h, r float32) *Path

RoundRect adds a rounded rectangle with a uniform radius.

type PathEntry

type PathEntry struct {
	Inline *Path // nil when external
	Hash   Hash
	Index  uint32
}

PathEntry is a decoded path table entry.

type PathRef

type PathRef uint32

Local resource references inside an object.

type Play

type Play struct {
	// Seq is the hash of the PartSeq part.
	Seq string `json:"seq,omitempty"`
	// Audio is the hash of the PartAudio part, and Type the media type of
	// the file it holds ("audio/mpeg").
	Audio string `json:"audio,omitempty"`
	Type  string `json:"type,omitempty"`
	// Cues is the hash of the cue index part (PartIndex), if any. Its
	// ticks are those of the Standard MIDI File, or milliseconds of the
	// audio.
	Cues string `json:"cues,omitempty"`
}

Play is what a view plays: the music of a score as a Standard MIDI File (Seq), or a recording as the audio file itself (Audio), and cues that tie its time to places on the pages (docs/spec.md §4.4). A view has one of Seq and Audio.

type PrefixMember

type PrefixMember struct {
	Index       int
	Rest        *Object
	RestFonts   []FontRef
	RestObjects []int
	// Bytes of the op stream the member no longer carries.
	Saved int
}

PrefixMember is a rewritten object: index into the input slice and the rest object, which references the prefix as its child object 0.

type PrefixShare

type PrefixShare struct {
	Prefix *Object
	// Fonts and child objects of Prefix, mapped back to the references of
	// the object at Members[0] (see Split).
	PrefixFonts   []FontRef
	PrefixObjects []int
	Members       []PrefixMember
}

PrefixShare is one shared prefix and the objects that were cut to use it.

func SharePrefixes

func SharePrefixes(objs []*Object, minBytes int) ([]PrefixShare, error)

SharePrefixes finds the longest legal instruction prefix that two or more of the objects have in common (at least minBytes of op stream) and returns, per distinct prefix, the shared object and the rewritten members. Objects that share nothing are absent from the result. The objects themselves are not modified.

Equality is by content: instruction bytes plus the paths, paints, fonts, images and child hashes they reference. Callers whose resource tables hold placeholders (fonts or children filled in later) must make the placeholders distinct per resource before calling.

type Reader

type Reader struct {
	Manifest *Manifest
	// contains filtered or unexported fields
}

Reader reads a document from either form.

An encrypted document opens locked: Manifest is then the outer manifest, whose parts are sealed, until Unlock replaces it with the document's own.

func OpenSingle

func OpenSingle(r io.ReaderAt, size int64) (*Reader, error)

OpenSingle parses the single-file form.

func OpenSingleFile

func OpenSingleFile(path string) (*Reader, error)

OpenSingleFile opens a single-form file by path. The parts are read from the file as they are asked for, so it stays open until Close.

func OpenSplit

func OpenSplit(dir string) (*Reader, error)

OpenSplit opens the split form from a directory.

func (*Reader) Close

func (r *Reader) Close() error

Close closes the file of a Reader from OpenSingleFile; the parts cannot be read after it. Readers opened in the other ways hold nothing to close.

func (*Reader) Encrypted

func (r *Reader) Encrypted() bool

Encrypted reports whether the document is encrypted.

func (*Reader) Entry

func (r *Reader) Entry(h Hash) (PartEntry, bool)

Entry returns the manifest entry for a part.

func (*Reader) Locked

func (r *Reader) Locked() bool

Locked reports whether the document is encrypted and not unlocked yet.

func (*Reader) Object

func (r *Reader) Object(h Hash) (*ObjectPart, error)

Object returns a decoded object part.

func (*Reader) Part

func (r *Reader) Part(h Hash) ([]byte, error)

Part returns the decoded bytes of a part. The parts of a locked document are its sealed parts, returned as they are stored.

func (*Reader) StoredManifest

func (r *Reader) StoredManifest() (*Manifest, []byte)

StoredManifest returns the manifest as the document stores it (that of an encrypted document is its outer manifest), and its JSON as it was read (decompressed). Signatures (package sign) cover the stored form, which needs no password.

func (*Reader) StoredPart

func (r *Reader) StoredPart(e PartEntry) ([]byte, error)

StoredPart returns the bytes of a part of the stored manifest as they are stored: compressed as its entry says, sealed for an encrypted document.

func (*Reader) Table

func (r *Reader) Table(id string) (*Table, []byte, error)

Table returns a table of the document (docs/spec.md §4.6) and the bytes of its Parquet file. The tables of a locked document cannot be read.

func (*Reader) ToDocument

func (r *Reader) ToDocument() (*Document, error)

ToDocument rebuilds a Document (for split/join round trips). An encrypted document must be unlocked first, and the Document it gives is not encrypted until a Lock is set; WriteSingle and WriteSplit of the Reader copy an encrypted document without its password.

func (*Reader) Unlock

func (r *Reader) Unlock(password string) error

Unlock opens an encrypted document with its password: it decrypts the manifest, which becomes Manifest, and lets Part decrypt parts. It returns ErrWrongPassword when no key slot opens with the password.

func (*Reader) UnlockECDH

func (r *Reader) UnlockECDH(priv *ecdh.PrivateKey) error

UnlockECDH opens an encrypted document with the private key it was sealed for (an ecdh key slot), as Unlock does with a password. It returns ErrWrongKey when no key slot opens with the key.

func (*Reader) WriteSegment

func (r *Reader) WriteSegment(w io.Writer, o SegmentOptions) error

WriteSegment writes a segment of the document in the single-file form (docs/spec.md §3.6). The document must be one of pages: its views fixed, flow or scroll, without music, and an encrypted one unlocked. The views of the segment have no text index (the text of the whole view). It may be called from several goroutines at once.

func (*Reader) WriteSingle

func (r *Reader) WriteSingle(w io.Writer) error

WriteSingle writes the document in the single-file form. The stored parts are copied as they are (after checking their hashes), so an encrypted document needs no password.

func (*Reader) WriteSplit

func (r *Reader) WriteSplit(dir string) error

WriteSplit writes the document in the split form into dir, copying the stored parts as WriteSingle does.

type Rect

type Rect struct {
	X, Y, W, H float32
}

Rect is an axis-aligned rectangle.

type RectDef

type RectDef struct {
	X float32 `json:"x"`
	Y float32 `json:"y"`
	W float32 `json:"w"`
	H float32 `json:"h"`
}

RectDef is a rectangle in JSON.

type Replay

type Replay struct {
	// contains filtered or unexported fields
}

Replay copies instructions of an object that was read into an object that is being built: the paths, paints, fonts, images and objects that the instructions refer to are added to the destination when they are first used. It is for a writer that draws a part of an object again (a group by itself, for its shadow); the bounding boxes of the objects that the instructions use are not known, so the destination needs a bounding box of its own (SetBBox).

func NewReplay

func NewReplay(part *ObjectPart, dst *Object) *Replay

NewReplay starts copying instructions of part into dst.

func (*Replay) Emit

func (r *Replay) Emit(in Instr) (err error)

Emit writes an instruction of the part to the destination. An instruction that refers to a resource the part does not have is an error, and is not written.

type Run

type Run [2]float32

Run is a run-length entry [count, size] for sheet rows/columns.

type SealedManifest

type SealedManifest struct {
	Part Hash `json:"part"`
	// Enc is the encoding of the manifest JSON inside the seal.
	Enc string `json:"enc"`
}

SealedManifest locates the sealed manifest.

type SearchText

type SearchText struct {
	Meta  Meta       `json:"meta"`
	Views []ViewText `json:"views"`
}

SearchText is the text of a document for a search index outside it: its metadata and the text of each view, page by page.

type Segment

type Segment struct {
	View string `json:"view"`
	From int    `json:"from"`
	To   int    `json:"to"`
}

Segment names the pages [From, To) of a view (0-based).

func SegmentAt

func SegmentAt(v *View, page, size int) Segment

SegmentAt returns the segment of size pages that holds page of v: a view's segments are pages [0, size), [size, 2·size) and so on, the last one shorter.

type SegmentOptions

type SegmentOptions struct {
	Segment
	// Have lists the pages the reader holds from earlier segments: the
	// parts they need are left out.
	Have []Segment
	// Lock seals the segment (NewECDHLock); nil writes it in the clear.
	Lock *Lock
}

SegmentOptions say which pages a segment carries and how it is sealed.

type Split

type Split struct {
	Prefix, Rest               *Object
	PrefixFonts, RestFonts     []FontRef
	PrefixObjects, RestObjects []int
}

Split is an object cut in two: Prefix draws the first instructions, Rest begins with USE of it (its object reference 0, to be set by the caller once the prefix has a hash), re-establishes the state and draws the remaining instructions. Both keep the original bounding box.

PrefixFonts / RestFonts and PrefixObjects / RestObjects map each font and child-object reference of the new objects back to the original one, in new-reference order (RestObjects[0] is the prefix placeholder, -1).

type Stop

type Stop struct {
	Offset float32
	Color  Color
}

Stop is a gradient color stop.

type Table

type Table struct {
	// ID names the table in the document ("chart-1", "sheet1", "data").
	ID    string `json:"id"`
	Title string `json:"title,omitempty"`
	// Part is the hash of the part that holds the Parquet file.
	Part string `json:"part"`
	// Rows is the count of rows, and Columns the columns, as the Parquet
	// file's schema has them: a listing without decoding the file.
	Rows    int64         `json:"rows"`
	Columns []TableColumn `json:"columns"`
	// View and Page tell where the figure the table is the data of is:
	// the view's id and the page in it, from 1 (0 for a view without
	// pages: the table of a sheet); "" when the table is not shown.
	View string `json:"view,omitempty"`
	Page int    `json:"page,omitempty"`
}

Table is a table a document holds beside its drawing (docs/spec.md §4.6): the data of a chart, the cells of a sheet, the rows of a CSV or Parquet file, as an Apache Parquet file in a PartTable part.

type TableColumn

type TableColumn struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

TableColumn is a column of a table: its name, and its type ("string", "number", "integer", "boolean", "date", "datetime" or "other"; encoding/parquet.Type).

type TextContent

type TextContent struct {
	Runs   []TextRun
	Nodes  []TextNode
	Links  []TextLink
	Images []TextImage
}

TextContent is the text of an object with its structure: the runs, the nodes they belong to, the links and the images, in walk order.

func ExtractContent

func ExtractContent(o *ObjectPart, resolve func(Hash) *ObjectPart) (*TextContent, error)

ExtractContent returns the runs of an object together with its structure (headings, lists, tables, figures: the MARKs of docs/spec.md §7.8), its links and its images, for text layers and for writing the document as text. The runs are the same as ExtractText's, and so are the limits.

type TextImage

type TextImage struct {
	Hash       Hash
	X, Y, W, H float32
	After      int // index of the last run before the image (-1 before the first)
	Node       int // the leaf, else the container, open at the image (-1 at the top level)
	Before     int // index of the first node made after the image (len(Nodes) at the image)
}

TextImage is an IMAGE or IMAGE_SUB: the part it draws, the bounding box it is drawn in, and where it came in the text.

type TextLink

type TextLink struct {
	X, Y, W, H float32
	URL        string
	After      int // index of the last run before the LINK (-1 before the first)
	Node       int // the leaf, else the container, open at the LINK (-1 at the top level)
}

TextLink is a LINK: the bounding box of its rectangle in the extraction space, and where it came in the text.

type TextNode

type TextNode struct {
	Kind   NodeKind
	Parent int // index of the enclosing node, -1 at the top level
	// Level is the level of a heading, 1 to 6, or 0 when the payload is
	// not a level.
	Level int
	// Cell is the place of a cell: relative to its table inside a TABLE,
	// that of the sheet outside one. Nil when the payload is not a
	// reference.
	Cell *CellRef
	// Alt is the alternative text of a figure ("" when it is decorative).
	Alt string
	// Data is the id of the table a figure is the data of (its DATA mark;
	// docs/spec.md §4.6), "" when it has none.
	Data string
	// Code says a paragraph is a line of code (the word "code" of its
	// payload; docs/spec.md §7.8).
	Code bool
	// Quote is how deep in quotations a paragraph or a list is: the count
	// of the word "quote" in its payload.
	Quote int
	// List is the kind of the markers of a list's items: "bullet",
	// "ordered", or "" when the payload does not say.
	List string
}

TextNode is a node of the structure of an object: what its MARKs say the text is (docs/spec.md §7.8). Nodes point at their parent by index.

type TextRun

type TextRun struct {
	Text    string
	X, Y    float32 // anchor after applying the transform
	Advance float32
	Size    float32
	Font    *Font
	Align   byte
	Matrix  [6]float32
	Sep     byte // separator from the previous run, from MARKs or position heuristics
	Ordinal int  // position in the extraction order of the top-level object
	AltText bool
	Node    int    // index of the structure node the run belongs to (TextContent.Nodes)
	Lang    string // BCP 47 language set by a LANG mark; "" for the document's default
}

TextRun is a text drawing instruction (or ALT_TEXT mark) located in the coordinate space of the object being walked.

func ExtractText

func ExtractText(o *ObjectPart, resolve func(Hash) *ObjectPart) ([]TextRun, error)

ExtractText returns the text runs of an object and the objects it USEs, in walk order. resolve must return decoded child objects (nil skips the child).

The objects may not draw each other deeper than MaxUseDepth, nor read more than MaxReusedInstructions from objects that are drawn again.

type View

type View struct {
	ID    string `json:"id"`
	Kind  string `json:"kind"`
	Title string `json:"title,omitempty"`

	// optional text index part (docs/spec.md §7.9)
	TextIndex string `json:"textIndex,omitempty"`

	// fixed / flow
	Pages      []*Page     `json:"pages,omitempty"`
	Continuous *Continuous `json:"continuous,omitempty"`
	// Direction is the order pages are put side by side in (spreads, a
	// horizontal row): DirectionLTR (the default when "") or DirectionRTL,
	// for books bound on the right (docs/spec.md §4.1).
	Direction string `json:"direction,omitempty"`

	// sheet
	Tile      float32           `json:"tile,omitempty"`
	Cols      []Run             `json:"cols,omitempty"`
	Rows      []Run             `json:"rows,omitempty"`
	Freeze    *Freeze           `json:"freeze,omitempty"`
	Gridlines bool              `json:"gridlines,omitempty"`
	Tiles     map[string]string `json:"tiles,omitempty"`
	TilesRef  string            `json:"tilesRef,omitempty"`

	// Play is the music a view plays (docs/spec.md §4.4).
	Play *Play `json:"play,omitempty"`
}

View is a viewing unit: a slide deck, a document, or a sheet.

func (*View) AddPage

func (v *View) AddPage(w, h float32, layers ...Layer) *Page

AddPage appends a page to a fixed/flow view.

func (*View) TileSize

func (v *View) TileSize() float32

TileSize returns the size of the tiles of a sheet view: Tile, or DefaultTile for a view that states none.

type ViewText

type ViewText struct {
	ID    string     `json:"id"`
	Kind  string     `json:"kind"`
	Title string     `json:"title,omitempty"`
	Pages []PageText `json:"pages"`
}

ViewText is the text of a view.