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
- Variables
- func Crop(img image.Image, box Box, scale int) (image.Image, error)
- func CropLogo(src []byte, box *Box, scale int) ([]byte, error)
- func EncodePicture(img image.Image, maxSide int) ([]byte, string, error)
- func FontName(s string) string
- func FullFile(n int) string
- func Half(img image.Image) image.Image
- func Line(s string, max int) string
- func MediaFile(n int, ext string) string
- func MediaFileOf(n int) string
- func Opaque(img image.Image) bool
- func PageFile(n int) string
- func ParseInfo(s string) (int, map[int]float64)
- func ParseTheme(b []byte) ([]Font, []Colour)
- func RunningText(b []byte) string
- func TakePicture(src []byte, box *Box, scale, maxSide int) ([]byte, string, error)
- func Text(s string) string
- func TextFile(n int) string
- func Trim(img image.Image) image.Image
- func ViewFile(n int) string
- type Box
- type Colour
- type Facts
- type Font
- type ImageRow
- type Kind
- type Staged
- type Tools
Constants ¶
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.
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.
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.
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.
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.
const FactsFile = "pages.json"
FactsFile is what Render writes beside the pages and pictures.
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.
const MinCropSide = 8
MinCropSide is the least width and height of a crop, in the pixels of the image the model was shown.
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.
const Schema = "pages/v1"
Schema is the format of FactsFile.
Variables ¶
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 ¶
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 ¶
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
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 ¶
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 MediaFileOf ¶
func ParseInfo ¶
ParseInfo reads pdfinfo's answer: the page count, and each listed page's longer side in points.
func ParseTheme ¶
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 ¶
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
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 ¶
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 Trim ¶ added in v0.7.29
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.
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 ¶
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 ¶
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"`
// 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.
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 ¶
ParseFontTable reads a Word document's font table: the name of each font it lists.
func ParseFonts ¶
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
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
ParseImageList reads `pdfimages -list`'s table, the two header lines left out and any row it cannot read skipped.
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"`
// 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 ¶
StagedFrom is the staged record of what was read: f's facts, under the document's name.
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. |