docpages

package
v0.7.44-dev.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package docpages is the document a Report Designer run is given to build a design around: one PDF, whose first pages poppler's page renderer turns into PNG images, or one Word document, whose theme part declares its fonts and colours and whose headers, footers and pictures are read as they are. The runner image's `pages` role does the reading in the decode image (Render), with no network, no capabilities and the document mounted read-only; the host holds what it wrote to Facts.Validate, re-encodes every image from its pixels and stages the result in the layout Staged names, which the tools server's document_pages and crop_logo read.

This package is part of the embedded runner-image build context and so imports nothing outside the standard library.

Index

Constants

View Source
const (
	// MaxDocumentBytes caps the document as given.
	MaxDocumentBytes = 20 << 20
	// MaxPages is how many of a PDF's pages are rendered: the first twelve.
	MaxPages = 12
	// RenderPPI is the resolution a page is rendered at, which a logo is
	// cropped from; ViewPPI, half of it, is the page the model looks at.
	RenderPPI = 220
	ViewPPI   = RenderPPI / 2
	// MaxPageSide caps a rendered page's longer side in pixels: a page
	// larger than about sixteen inches is scaled to fit rather than
	// rendered at RenderPPI.
	MaxPageSide = 3600
	// MaxPageBytes caps one rendered page's PNG.
	MaxPageBytes = 24 << 20
	// MaxMedia and MaxMediaBytes cap a Word document's pictures.
	MaxMedia      = 8
	MaxMediaBytes = 4 << 20
	// MaxMediaSide caps a picture's width and height, checked before it is
	// decoded.
	MaxMediaSide = 4096
	// MaxFonts, MaxColours and MaxRunning cap the lists of Facts;
	// MaxNameRunes a font's name and MaxRunningRunes a header's or a
	// footer's text.
	MaxFonts        = 24
	MaxColours      = 16
	MaxRunning      = 6
	MaxNameRunes    = 64
	MaxRunningRunes = 300
	// MaxFactsBytes caps FactsFile as the host reads it.
	MaxFactsBytes = 256 << 10
)

The bounds of one document.

View Source
const (
	// FailureMalformed: the document could not be read as its kind.
	FailureMalformed = "malformed"
	// FailureLocked: the document needs a password to open.
	FailureLocked = "locked"
	// FailureTime: a page took longer than its limit to render.
	FailureTime = "time"
	// FailureMemory: the renderer ran out of the container's memory.
	FailureMemory = "memory"
	// FailureEmpty: the document has no page to render.
	FailureEmpty = "empty"
)

The kinds of failure, the only words of a failed read that leave the decode image: the decoders' own text never does.

View Source
const (
	// MinPictureSide is the least width and height of a picture worth
	// offering: anything smaller is a bullet, a rule or a texture tile.
	MinPictureSide = 32
	// MaxPicturePixels caps a picture pdfimages wrote, checked before a
	// byte of it is decoded.
	MaxPicturePixels = 4096 * 4096
	// MaxPictureFileBytes caps one file pdfimages wrote, as read.
	MaxPictureFileBytes = 64 << 20
	// PictureJPEGQuality is the quality an opaque picture is written at.
	PictureJPEGQuality = 90
	// MaxPictureSide caps a PDF picture's sides as written: a larger one
	// is halved until it fits, past what a cover image keeps.
	MaxPictureSide = 2048
	// MaxStagedMediaBytes caps a picture as the CLI stages it, a PNG the
	// document tools read: a larger one is halved until it fits.
	MaxStagedMediaBytes = 4 << 20
)

The bounds of a PDF's pictures.

View Source
const (
	StagedDir  = "document"
	StagedFile = "document/document.json"
	ViewDir    = "document/pages"
	FullDir    = "document/full"
	TextDir    = "document/text"
	MediaDir   = "document/media"
)

The document as the CLI stages it for a Report Designer run, under the run's inputs folder: StagedFile with what was read of it, the pages the model looks at (ViewDir/<n>.png, at ViewPPI), the same pages at RenderPPI a logo is cropped from (FullDir/<n>.png), the text of each page (TextDir/<n>.txt; a Word document's whole text is 1.txt) and a Word document's pictures (MediaDir/<n>.png). Every image is the CLI's own encoding of the pixels it read; the document itself is never staged.

View Source
const (
	// MaxPageText caps one page's text as staged.
	MaxPageText = 16 << 10
	// MaxDocxText caps a Word document's whole text as staged.
	MaxDocxText = 64 << 10
	// MaxStagedBytes caps StagedFile as the tools server reads it.
	MaxStagedBytes = 64 << 10
)

The bounds of the staged text.

View Source
const FactsFile = "pages.json"

FactsFile is what Render writes beside the pages and pictures.

View Source
const LogoSide = 1024

LogoSide is the most a cropped logo's side may be, a design logo's cap: a larger crop is halved until it fits.

View Source
const MinCropSide = 8

MinCropSide is the least width and height of a crop, in the pixels of the image the model was shown.

View Source
const (
	// PageTimeout stops one page's render, and each of pdfinfo's and
	// pdffonts' runs.
	PageTimeout = 60 * time.Second
)

The time limits of one document's reading.

View Source
const Schema = "pages/v1"

Schema is the format of FactsFile.

Variables

View Source
var Failures = map[string]string{
	FailureMalformed: "it could not be read as a PDF or a Word document",
	FailureLocked:    "it needs a password to open",
	FailureTime:      "a page took longer than its limit to render",
	FailureMemory:    "a page ran out of the renderer's memory",
	FailureEmpty:     "it has no page to render",
}

Failures says each kind of failure in words for the model and the person.

Functions

func Crop

func Crop(img image.Image, box Box, scale int) (image.Image, error)

Crop is the part of img that box names, where box is in pixels of an image scale times smaller than img (a page shown at ViewPPI and cropped from its render at RenderPPI has scale 2). A box partly outside the image is cut to it; one smaller than MinCropSide, or outside, is refused.

func CropLogo(src []byte, box *Box, scale int) ([]byte, error)

CropLogo is the logo a box of src, a PNG, names: the crop (Crop at scale; the whole image when box is nil), its blank margin trimmed (Trim), halved until no side is over LogoSide, encoded as a PNG at the best compression. crop_logo makes it to show the model and draw in previews; the CLI makes it again from its own copy of the page to keep.

func EncodePicture added in v0.7.29

func EncodePicture(img image.Image, maxSide int) ([]byte, string, error)

EncodePicture is img as the file a picture is written as: scaled by halves until no side is over maxSide, then a PNG when it has transparency, else a JPEG at PictureJPEGQuality (a photograph stays a photograph's size). It answers the bytes and "png" or "jpg".

func FontName

func FontName(s string) string

FontName is a font's name as a PDF embeds it, without the six-letter subset tag ("ABCDEF+SourceSerif4-Regular" is "SourceSerif4-Regular"), cut to one printable line within MaxNameRunes; empty when nothing is left.

func FullFile

func FullFile(n int) string

func Half

func Half(img image.Image) image.Image

Half is img at half its width and height, each pixel the mean of four.

func Line

func Line(s string, max int) string

Line is s as one line of printable text, spaces collapsed, cut to max runes.

func MediaFile

func MediaFile(n int, ext string) string

MediaFile is picture n's file as Render writes it; ext is png or jpg.

func MediaFileOf

func MediaFileOf(n int) string

func Opaque added in v0.7.29

func Opaque(img image.Image) bool

Opaque says every pixel of img is opaque.

func PageFile

func PageFile(n int) string

PageFile is page n's PNG as Render writes it.

func ParseInfo

func ParseInfo(s string) (int, map[int]float64)

ParseInfo reads pdfinfo's answer: the page count, and each listed page's longer side in points.

func ParseTheme

func ParseTheme(b []byte) ([]Font, []Colour)

ParseTheme reads a Word theme part (DrawingML): the heading and body faces of its font scheme and the colours of its colour scheme, each by its role.

func RunningText

func RunningText(b []byte) string

RunningText is the text of a Word header or footer part, its paragraphs joined by " / ", as one line within MaxRunningRunes.

func TakePicture added in v0.7.29

func TakePicture(src []byte, box *Box, scale, maxSide int) ([]byte, string, error)

TakePicture is the picture a box of src, a PNG, names (Crop at scale; the whole image when box is nil), as EncodePicture writes it within maxSide: a PNG when it has transparency, else a JPEG. take_picture makes it to show the model and draw in previews; the CLI makes it again from its own copy of the page to keep.

func Text

func Text(s string) string

Text is a page's text with every control and format character taken out but the line breaks and tabs: what pdftotext and pandoc write can carry escape sequences, bidirectional overrides and invisible characters a reader of the text would not see.

func TextFile

func TextFile(n int) string

func Trim added in v0.7.29

func Trim(img image.Image) image.Image

Trim is img without the margin around what it shows: the rows and columns at its edges that hold only transparent pixels or the colour of its top left corner (white paper, or the colour of a band a logo sits on), with a little of that margin kept, a twentieth of the longer side that is left and at least two pixels. An image that is all margin is answered as it is.

func ViewFile

func ViewFile(n int) string

ViewFile, FullFile, TextFile and MediaFileOf are the staged files of page or picture n.

Types

type Box

type Box struct {
	X      int `json:"x"`
	Y      int `json:"y"`
	Width  int `json:"width"`
	Height int `json:"height"`
}

Box is a rectangle on an image the model was shown, in its pixels.

type Colour

type Colour struct {
	Hex   string `json:"hex"`
	Role  string `json:"role,omitempty"`
	Share int    `json:"share,omitempty"`
}

Colour is a colour of the document: a Word theme's declared colour by its role (accent1, dk2, hlink…), or a colour found on a PDF's rendered pages with the share of the inked area it covers, in percent.

func PageColours

func PageColours(pages []image.Image) []Colour

PageColours are the colours that ink the most of pages, white left out: each pixel (every other one, each way) falls in a bucket of 16 shades a channel, and each of the largest buckets is answered as the mean of its pixels with its share of the inked area in percent, from the largest, those under one percent left out.

type Facts

type Facts struct {
	Schema string `json:"schema"`
	Kind   Kind   `json:"kind"`
	// Pages is a PDF's page count; Rendered how many of its first pages
	// were rendered, as PageFile(1) to PageFile(Rendered).
	Pages    int      `json:"pages,omitempty"`
	Rendered int      `json:"rendered"`
	Fonts    []Font   `json:"fonts,omitempty"`
	Colours  []Colour `json:"colours,omitempty"`
	// Headers and Footers are a Word document's running text, part by
	// part.
	Headers []string `json:"headers,omitempty"`
	Footers []string `json:"footers,omitempty"`
	// Media are the document's pictures as written, MediaFile(n, ext): a
	// Word document's, or the pictures a PDF's rendered pages draw, each
	// once, with MediaPages the page each is first drawn on. MediaSkipped
	// counts the pictures it has that were not read: a drawing in another
	// format (EMF, WMF, SVG), one past MaxMediaBytes, or one past
	// MaxMedia.
	Media        []string `json:"media,omitempty"`
	MediaPages   []int    `json:"mediaPages,omitempty"`
	MediaSkipped int      `json:"mediaSkipped,omitempty"`
	// Failure is why nothing of the document could be read; Stopped why a
	// PDF's rendering stopped before its last page to render. Each is a
	// kind of failure.
	Failure string `json:"failure,omitempty"`
	Stopped string `json:"stopped,omitempty"`
}

Facts is FactsFile: what the pages role read of a document.

func Render

func Render(ctx context.Context, src string, kind Kind, out, scratch string, t Tools) (Facts, error)

Render reads the document at src, of kind, and writes FactsFile with what it found beside the pages (PDF) or the pictures (Word) under out; scratch is where a page is rendered before its capped copy is made. A document that cannot be read is a Facts with its Failure, never an error: the error is this role's own failure to write.

func (Facts) Validate

func (f Facts) Validate() error

Validate holds Facts to what Render can write: the host reads it from a container that parsed a document no one checked, so nothing in it is trusted past these rules.

type Font

type Font struct {
	Name string `json:"name"`
	// Role is "headings" or "body" for a theme's faces, empty otherwise.
	Role string `json:"role,omitempty"`
}

Font is a font the document names: in a PDF, a font a rendered page uses; in a Word document, its theme's heading and body faces and the fonts its font table lists.

func ParseFontTable

func ParseFontTable(b []byte) []Font

ParseFontTable reads a Word document's font table: the name of each font it lists.

func ParseFonts

func ParseFonts(s string) []Font

ParseFonts reads pdffonts' table: each font's name, the subset tag taken off, once each, in the order listed, within MaxFonts.

type ImageRow added in v0.7.29

type ImageRow struct {
	Page, Num     int
	Type          string
	Width, Height int
	Object        string
}

ImageRow is one row of `pdfimages -list`: the page it is drawn on, its number among the images listed (the file pdfimages writes for it), its type (image, smask, mask, stencil), its size in pixels and the PDF object it is.

func ParseImageList added in v0.7.29

func ParseImageList(s string) []ImageRow

ParseImageList reads `pdfimages -list`'s table, the two header lines left out and any row it cannot read skipped.

type Kind

type Kind string

Kind is the kind of document.

const (
	KindPDF  Kind = "pdf"
	KindDOCX Kind = "docx"
)

The kinds.

type Staged

type Staged struct {
	Kind Kind `json:"kind"`
	// Name is the document's file name as the person gave it, one line.
	Name     string   `json:"name"`
	Pages    int      `json:"pages,omitempty"`
	Rendered int      `json:"rendered"`
	Fonts    []Font   `json:"fonts,omitempty"`
	Colours  []Colour `json:"colours,omitempty"`
	Headers  []string `json:"headers,omitempty"`
	Footers  []string `json:"footers,omitempty"`
	// Media is how many pictures are staged, MediaDir/1.png on, with
	// MediaPages the page of a PDF each is first drawn on, and
	// MediaSkipped how many the document has that were not read.
	Media        int   `json:"media,omitempty"`
	MediaPages   []int `json:"mediaPages,omitempty"`
	MediaSkipped int   `json:"mediaSkipped,omitempty"`
	// Texts is how many texts are staged, TextDir/1.txt on; TextCut says
	// one was cut to its cap.
	Texts   int  `json:"texts,omitempty"`
	TextCut bool `json:"textCut,omitempty"`
	// Failure and Stopped are Facts'.
	Failure string `json:"failure,omitempty"`
	Stopped string `json:"stopped,omitempty"`
	// LogoGiven says the person gave the run a logo of their own, which a
	// crop never replaces.
	LogoGiven bool `json:"logoGiven,omitempty"`
}

Staged is StagedFile.

func StagedFrom

func StagedFrom(f Facts, name string, media, texts int, cut, logoGiven bool) Staged

StagedFrom is the staged record of what was read: f's facts, under the document's name.

func (Staged) Validate

func (s Staged) Validate() error

Validate holds a staged record to its bounds.

type Tools

type Tools struct {
	PDFToPPM, PDFInfo, PDFFonts, PDFImages string
}

Tools are the absolute paths of poppler's programs Render runs; zero values take the decode image's.

Directories

Path Synopsis
Package docpagestest makes the documents the Report Designer's tests read: a PDF of plain pages and a Word document with a theme, running text and a picture.
Package docpagestest makes the documents the Report Designer's tests read: a PDF of plain pages and a Word document with a theme, running text and a picture.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL