Documentation
¶
Overview ¶
Package reportdesign is the one definition of a report design: the theme document version 3 that sets the look of a person's PDF reports, a whole brand. The server validates a design with it before storing one in the account's library, the CLI before the runner's template reads one, and the desktop before it saves one; the site's editor reads the same rules through the openapi's ReportDesign schema, which a core test holds to Schema.
A design is data, never markup, with one bounded exception. Colours are #rrggbb; fonts, title blocks, heading treatments, heading scales, margins, quote styles, paper, page numbers, header styles, cover styles and cover facts are names from closed lists; every free text (the design's name, the brand block's lines, the header's and the footer's slots) is one line of plain text that the template sets as content, never evaluates. A slot may name a token of a closed set ({title}, {page}, …), which the template substitutes before it sets the text; anything else between braces is literal. There is no path, URL or file name in a design: the brand's website is drawn as text. The one exception is the custom cover's Typst source, which is code: bounded, compiled only under the renderer's confinement with the render root as its whole world, and carried only inside a document this package validated (cover.go).
The images (the logo, the cover image, a custom cover's images and thumbnail) are the person's own pixels, as this package re-encoded them (logo.go, image.go), never a URL. They sit outside the document's byte cap and a server answers them only when asked.
The look stays restrained: an accent and an optional secondary colour, each with a derived tint; body text is near-black whatever the design. Where a colour touches text it must reach 4.5:1 on white, and where it colours only graphics 3:1. Which it is follows from the design, and the runner's template must draw it so (AccentOnText, SecondaryOnText):
- titleBlock "band" sets the title in white on a full-width accent band;
- headings "smallcaps" and "numbered" set level 1 and 2 headings in the accent;
- a cover that is drawn (cover.when is not "never") puts text on or in a colour as its style declares (CoverStyles): "band" and "largeType" the accent, "plate" and "custom" the accent too (each draws as "band" when it cannot be drawn as itself), "split" the secondary, or the accent when the design has none;
- every other choice colours only rules, bars, shapes, tinted cells and callout edges, and keeps text near-black.
Index ¶
- Constants
- Variables
- func BuiltinDocument(id string) ([]byte, bool)
- func BuiltinIDs() []string
- func Contrast(a, b string) (float64, error)
- func CoverStyleNames() []string
- func ExpandSlot(slot string, facts map[string]string) string
- func FontsFor(role string) []string
- func NearestPassing(colour string, min float64) (string, error)
- func Schema() []byte
- func Tint(accent string) (string, error)
- func TokensIn(slot string) []string
- type Brand
- type Cover
- type CoverStyle
- type CustomCover
- type Design
- func (d Design) AccentOnText() bool
- func (d Design) Canonical() []byte
- func (d Design) MinContrast() float64
- func (d Design) MinSecondaryContrast() float64
- func (d Design) SHA256() string
- func (d Design) SecondaryOnText() bool
- func (d Design) Validate() error
- func (d Design) Version2() []byte
- func (d Design) WithoutAssets() Design
- type Family
- type FieldError
- type Fonts
- type Footer
- type Header
- type Image
- type Kind
- type Logo
- type Suggestion
- type Tables
Constants ¶
const ( // TextContrast is the least contrast for an accent that touches text. TextContrast = 4.5 // GraphicsContrast is the least for an accent on graphics only. GraphicsContrast = 3.0 )
The contrast a design's accent must reach on white (WCAG 2.2 1.4.3 and 1.4.11).
const ( // MaxCoverSourceBytes caps the custom cover's Typst source. MaxCoverSourceBytes = 32 << 10 // MaxCoverImages caps the images a custom cover carries. MaxCoverImages = 6 // MaxCoverImagesBytes caps a custom cover's images in all, as encoded // again. MaxCoverImagesBytes = 2 << 20 // MaxThumbnailBytes caps the thumbnail, a PNG of the cover's last // render, kept for the editors. MaxThumbnailBytes = 300 << 10 )
The custom cover: the one field of a design that is code. Its source is Typst, written by the person or by the Report Designer on their behalf, which the runner's template calls as a function of the facts it has (the title, the author, the date, the brand, the design's colours and faces, the logo's and the images' paths) to draw the cover page when the cover style is "custom". The renderer compiles it only under the confinement every export runs in, with the render root as its whole world: it can read the report, the design, the facts and the images copied there, none of which is secret, and it has no shell, no network, no package imports and no file writes. A custom cover that fails to compile, draws more or fewer than one page, or leaves an image untagged is passed over for the design's built-in cover style, and the export goes on.
This package holds the cover to its bounds and carries it only inside a document it validated; it does not read the code.
const ( // MaxCoverImageUploadBytes caps an uploaded image before a byte of it // is decoded. MaxCoverImageUploadBytes = 2 << 20 // MaxCoverImageBytes caps a design's cover image as encoded again. MaxCoverImageBytes = 2 << 20 // MaxCoverImageSide caps a cover image's width and height in pixels. A // larger upload is scaled down to fit; across a page's width this is // past 240 dpi. MaxCoverImageSide = 2048 // MaxCoverImageUploadPixels caps what an upload may make the decoder // allocate. MaxCoverImageUploadPixels = 4096 * 4096 // JPEGQuality is the quality a JPEG is encoded again at. JPEGQuality = 90 )
The images a design carries beyond its logo: the cover image, a custom cover's images and its thumbnail. Each is the person's own upload, never the model's and never a URL: NormalizeCoverImage decodes it, scales it down to fit MaxCoverImageSide and encodes it again from the pixels, a PNG as PNG and a JPEG as JPEG (a photograph stays a photograph's size), so no chunk, segment, profile or metadata of the upload survives.
const ( // MaxLogoUploadBytes caps an uploaded image before a byte of it is // decoded. MaxLogoUploadBytes = 512 << 10 // MaxLogoBytes caps a design's logo, the PNG itself: a PNG encoder // can write more than the upload was, and a logo too detailed for // this is refused rather than degraded. MaxLogoBytes = 512 << 10 // MaxLogoSide caps a logo's width and height in pixels. A larger upload // is scaled down to fit; a title block draws a logo a few centimetres // wide, and this is past 300 dpi at that size. MaxLogoSide = 1024 // MaxLogoUploadPixels caps what an upload may make the decoder // allocate, as the registry's image proxy does. MaxLogoUploadPixels = 4096 * 4096 )
The logo: a person's own image, drawn in the title block, on a cover whose facts include it and in a logoLeft header. It comes from the person, never from the model and never from a URL: a design carries its pixels, as a PNG this package wrote from them.
An upload is a PNG or a JPEG, at most MaxLogoUploadBytes; NormalizeLogo decodes it, scales it down to fit MaxLogoSide and encodes it again as PNG from the decoded pixels, so no chunk, profile or metadata of the upload survives. A design's logo field is held by Validate to a PNG within the same bounds; the server stores only what NormalizeLogo wrote.
const ( // MaxDocumentBytes caps a design's canonical document without its // images and its custom cover. A canonical design is well under it; // the cap bounds what a client may make the server parse and store. MaxDocumentBytes = 24 << 10 // MaxNameRunes caps the design's name and the brand's name, labels the // person sees. MaxNameRunes = 60 // MaxLineRunes caps every other line of text: the brand's strapline, // contact lines, website and confidentiality line, and each header and // footer slot. MaxLineRunes = 120 // MaxContactLines caps the brand block's contact lines. MaxContactLines = 4 // SlotCount is the number of slots in the header and in the footer: // left, centre, right. SlotCount = 3 // MaxVersion caps the design's revision number. MaxVersion = 1_000_000 // MaxLibrary caps an account's library: how many designs it keeps. MaxLibrary = 10 )
Bounds on a design.
const DefaultID = "plain"
DefaultID is the theme a run takes when nothing else chose one.
const DocumentVersion = 3
DocumentVersion is the value of "agentryTheme" this package reads. A theme document of version 1 or 2 is refused, with no mapping.
MaxFooterTextRunes is the cap on the footer's one line in a version-2 document, which Version2 writes from a slot: one slot's worth.
const TintMix = 0.12
TintMix is the accent's share of its tint, the rest white (the tint is derived, never stored). The site's editor mixes the same.
const Version2Document = 2
Version2Document is the value of "agentryTheme" in a version-2 document, the projection a renderer that reads only version 2 is handed.
const White = "#ffffff"
White is the page.
Variables ¶
var ( // ErrImageTooLarge is an upload or an image over a byte or pixel bound. ErrImageTooLarge = errors.New("image too large") // ErrImageFormat is an image that is not a PNG or a JPEG, not the // format its place takes, or does not decode. ErrImageFormat = errors.New("image not a PNG or JPEG") )
The kinds of an image's refusal, for errors.Is on a *FieldError: a server answers an upload over a bound differently from one in no format it reads.
var ( ErrLogoTooLarge = ErrImageTooLarge ErrLogoFormat = ErrImageFormat )
ErrLogoTooLarge and ErrLogoFormat are the logo's names for the same two kinds.
var ( Papers = []string{"a4", "letter"} TitleBlocks = []string{"band", "bar", "ruled", "none"} HeadingStyles = []string{"rule", "bar", "smallcaps", "numbered", "plain"} HeadingScales = []string{"compact", "regular", "generous"} MarginPresets = []string{"narrow", "regular", "wide"} QuoteStyles = []string{"callout", "plain"} PageNumberStyles = []string{"none", "n", "nOfN"} HeaderStyles = []string{"none", "rule", "brandLine", "titleAndPage", "logoLeft"} CoverFacts = []string{"title", "subtitle", "author", "date", "brand", "logo", "confidentiality"} CoverWhens = []string{"long", "always", "never"} )
The closed lists. Each is the whole set of accepted names, in the order an editor offers them.
var ErrNoColour = errors.New("the logo has no colour to suggest")
ErrNoColour is a logo with nothing to read: every pixel transparent or white.
var MaxDocumentWithAssets = MaxDocumentBytes + base64.StdEncoding.EncodedLen(MaxLogoBytes) + base64.StdEncoding.EncodedLen(MaxCoverImageBytes) + 6*MaxCoverSourceBytes + base64.StdEncoding.EncodedLen(MaxCoverImagesBytes) + base64.StdEncoding.EncodedLen(MaxThumbnailBytes) + 1<<10
MaxDocumentWithAssets is the most a document may be as sent with every image at its largest and the custom cover at its bounds: the base64 of each image, the source escaped for JSON (a line break or a quote takes two bytes, a control character six) and a margin for the keys around them, over MaxDocumentBytes for the document itself. A server reads a design's body up to this.
var Tokens = []string{"title", "author", "date", "page", "pages", "brand", "section", "confidentiality"}
Tokens is the closed set a header or footer slot may name, each written between braces ({title}): the report's title, its author, its date, the page number, the page count, the brand's name, the current level-1 heading, and the brand's confidentiality line. The template substitutes them and sets the result as content, never evaluates it; anything else between braces is literal text.
Functions ¶
func BuiltinDocument ¶
BuiltinDocument is a built-in theme's embedded document, as shipped.
func BuiltinIDs ¶
func BuiltinIDs() []string
BuiltinIDs is the built-in themes' ids, in the order they are offered.
func CoverStyleNames ¶ added in v0.7.4
func CoverStyleNames() []string
CoverStyleNames is the cover styles' names.
func ExpandSlot ¶ added in v0.7.4
ExpandSlot substitutes a slot's tokens from facts, keyed by token name without the braces, and leaves everything else as it is, braces around an unknown word included: a token is a name of Tokens between a brace pair with no brace inside it. A token facts does not name expands to nothing.
func NearestPassing ¶
NearestPassing is the shade of a colour that reaches min contrast on white with the least change: the colour itself when it passes, else the lightest darkening of it (the same hue and saturation, a lower lightness) that does. The editor offers it when it refuses an accent.
func Schema ¶
func Schema() []byte
Schema is the theme document's JSON Schema (draft 2020-12), built from the same lists Validate reads, so it cannot drift from them. The openapi's ReportDesign schema is held to it by the core's api tests.
The schema says what a document may hold, the families each role takes included. The rules it cannot say are Validate's alone: each colour's contrast on white (MinContrast, MinSecondaryContrast), that a text is one line of plain text (not only spaces, no control, line-break or invisible format characters), the brand website's form, that a cover fact is named once, the custom cover's byte bounds (the schema counts characters) and what an image's base64 must hold: a PNG or a JPEG within its bounds.
Types ¶
type Brand ¶ added in v0.7.4
type Brand struct {
// Name is the brand's name, at most MaxNameRunes; the {brand} token.
Name string `json:"name"`
// Strapline is one line under the name, at most MaxLineRunes.
Strapline string `json:"strapline"`
// Contact is up to MaxContactLines lines (an address, a telephone, an
// email), each at most MaxLineRunes and none empty.
Contact []string `json:"contact"`
// Website is a host name or an https address, at most MaxLineRunes,
// drawn as text and never made a link by the template.
Website string `json:"website"`
// Confidentiality is a line such as "Confidential", at most
// MaxLineRunes; the {confidentiality} token.
Confidentiality string `json:"confidentiality"`
}
Brand is the brand block: who the report is from. Every line is optional ("" or no contact lines for none) and is drawn where a header, a footer or a cover asks for it, as text.
type Cover ¶ added in v0.7.4
type Cover struct {
// Style is a CoverStyles value: a built-in layout, or "custom" for the
// design's custom cover (which falls back to "band" when it cannot be
// drawn).
Style string `json:"style"`
// Shows are the facts the cover carries, each a CoverFacts value, no
// value twice, in the order given.
Shows []string `json:"shows"`
// When is a CoverWhens value: "long" draws the cover for a titled
// report past the template's length threshold, "always" for every
// titled report, "never" for none.
When string `json:"when"`
}
Cover is the cover page.
type CoverStyle ¶ added in v0.7.4
type CoverStyle struct {
// Name is the style's name, a Cover.Style value.
Name string
// AccentOnText says the accent carries text: white text on an accent
// panel, or the title set in the accent.
AccentOnText bool
// SecondaryOnText says the secondary carries text, or the accent does
// when the design has no secondary.
SecondaryOnText bool
}
CoverStyle is a cover layout and its declaration of which of the design's colours carry text on it, which the contrast rule reads.
func CoverStyleByName ¶ added in v0.7.4
func CoverStyleByName(name string) (CoverStyle, bool)
CoverStyleByName finds a cover style by its name.
func CoverStyles ¶ added in v0.7.4
func CoverStyles() []CoverStyle
CoverStyles is every cover style with its declaration, in the order an editor offers them.
type CustomCover ¶ added in v0.7.4
type CustomCover struct {
// Source is the Typst source, at most MaxCoverSourceBytes.
Source string `json:"source"`
// Images are the images the source may draw, each a PNG or a JPEG the
// core encoded again, in the order the renderer names them; at most
// MaxCoverImages, and MaxCoverImagesBytes in all.
Images []Image `json:"images"`
// Thumbnail is a PNG of the cover's last render, at most
// MaxThumbnailBytes; the zero Image is none, and is not written.
Thumbnail Image `json:"thumbnail,omitzero"`
}
CustomCover is a design's custom cover. The zero CustomCover is none, and a design without one has no "customCover" key.
func (CustomCover) IsZero ¶ added in v0.7.4
func (c CustomCover) IsZero() bool
IsZero reports whether the custom cover is none, which the canonical document leaves out.
func (CustomCover) Validate ¶ added in v0.7.4
func (c CustomCover) Validate() error
Validate holds the custom cover to its bounds: a source that is not empty, UTF-8 text with no control character but a tab, a line feed or a carriage return, at most MaxCoverSourceBytes; at most MaxCoverImages images, each a PNG or a JPEG within the cover image's pixel bound, and MaxCoverImagesBytes in all; a thumbnail that is a PNG of at most MaxThumbnailBytes.
type Design ¶
type Design struct {
// AgentryTheme is the document version, always DocumentVersion.
AgentryTheme int `json:"agentryTheme"`
// Name is the design's label: a built-in's own name, or the person's.
Name string `json:"name"`
// BasedOn is the id of the built-in theme the design started from.
BasedOn string `json:"basedOn"`
// Version is the design's revision, a positive integer. A built-in
// carries Agentry's revision of it; an edited design keeps the number
// it was loaded with unless its editor says otherwise.
Version int `json:"version"`
// Paper is a Papers value: "a4" or "letter" (US Letter).
Paper string `json:"paper"`
Fonts Fonts `json:"fonts"`
// Accent is the first colour, #rrggbb in lower case. Its tint is
// derived (Tint), never stored.
Accent string `json:"accent"`
// Secondary is the second colour, #rrggbb in lower case, or "" for
// none. Its tint is derived as the accent's is.
Secondary string `json:"secondary"`
// TitleBlock is a TitleBlocks value, the title's treatment on page 1.
TitleBlock string `json:"titleBlock"`
// Headings is a HeadingStyles value, the treatment of level 1 and 2.
Headings string `json:"headings"`
// HeadingScale is a HeadingScales value, how much larger than the
// body each heading level is set.
HeadingScale string `json:"headingScale"`
// Margins is a MarginPresets value, the page's margins.
Margins string `json:"margins"`
Tables Tables `json:"tables"`
// Quotes is a QuoteStyles value.
Quotes string `json:"quotes"`
Brand Brand `json:"brand"`
Header Header `json:"header"`
Cover Cover `json:"cover"`
// Logo is the person's logo, drawn in the title block, on the cover
// where its facts include it and in a logoLeft header; the zero Logo
// is none, and is not written.
Logo Logo `json:"logo,omitzero"`
// CoverImage is the design's cover image, drawn by the plate cover
// style and offered to a custom cover; the zero Image is none, and is
// not written.
CoverImage Image `json:"coverImage,omitzero"`
// CustomCover is the design's custom cover, drawn when the cover style
// is "custom"; the zero CustomCover is none, and is not written.
CustomCover CustomCover `json:"customCover,omitzero"`
}
Design is a report design: the theme document, version 3. Field order is the canonical JSON's key order.
func Builtins ¶
func Builtins() []Design
Builtins is every built-in theme, in the order they are offered.
func Parse ¶
Parse reads a design document and validates it: every field present but the optional images and custom cover (a "logo": null is no logo, as if the key were left out, and so for "coverImage" and "customCover"), no other key, no second value after it, at most MaxDocumentBytes in its canonical form besides the images and the custom cover, and every rule of Validate. A refusal is a *FieldError.
func (Design) AccentOnText ¶
AccentOnText reports whether the design sets text in its accent or on it: a band title block (the title in white on the accent), headings set in the accent (smallcaps, numbered), or a cover that is drawn in a style that declares the accent (band, largeType, plate, custom; split without a secondary). The runner's template draws exactly these with the accent on text; everything else colours only graphics.
func (Design) Canonical ¶
Canonical is the design's canonical document: its JSON in field order, indented by two spaces, with a final newline. A built-in's embedded document is exactly its Canonical, and the receipt hashes it, the images and the custom cover included. A design without a logo, a cover image or a custom cover has no key for it. Characters such as "&" and "<" are written as they are, not escaped.
func (Design) MinContrast ¶
MinContrast is the contrast the design's accent must reach on white: 4.5:1 where it touches text, 3:1 where it colours only graphics.
func (Design) MinSecondaryContrast ¶ added in v0.7.4
MinSecondaryContrast is the contrast the design's secondary must reach on white, by the same rule.
func (Design) SHA256 ¶
SHA256 is the lower-case hex SHA-256 of Canonical, the design's identity in a run's receipt.
func (Design) SecondaryOnText ¶ added in v0.7.4
SecondaryOnText reports whether the design sets text on its secondary: a cover that is drawn in a style that declares it (split), when the design has a secondary.
func (Design) Validate ¶
Validate holds a design to every rule: the version, the closed lists, the fonts' roles, the colours' form and contrast, every line of text, the slots, the cover's facts, and the images and the custom cover when it has them. A refusal is a *FieldError naming the first field found wrong, in document order, the contrast rule last among the document's own fields because the styles that decide it come after the colours.
func (Design) Version2 ¶ added in v0.7.4
Version2 is the design's version-2 projection, as a canonical version-2 document: what a renderer that reads only version 2 draws in its place. The accent, the faces, the title block, the headings, the tables, the quotes and the page numbers carry over; a family version 2 did not have becomes the nearest of its first fourteen (Family.Version2); a built-in version 2 did not have becomes the nearest of its five; the footer's line is the first slot that has text, its {brand} and {confidentiality} tokens filled from the brand block and its other tokens dropped, cut to MaxFooterTextRunes; the secondary, the brand block, the header, the cover, the heading scale, the margins, the cover image and the custom cover are left out, since version 2 has no place for them. The logo carries over. Version 2's rule on the accent (4.5:1 on white under a band title or smallcaps or numbered headings, 3:1 otherwise) asks no more of it than this version's, so a design that validates projects to one that does.
func (Design) WithoutAssets ¶ added in v0.7.4
WithoutAssets is the design with no logo, cover image or custom cover: the document a server stores and answers unless asked for its assets.
type Family ¶
type Family struct {
// Name is the family's name as Typst and the web fonts know it.
Name string
Kind Kind
// HeadingsOnly marks a display face, offered for headings only.
HeadingsOnly bool
// Version2 is the family a version-2 projection of a design names in
// its place: the family itself where version 2 knew it, else the
// nearest of the first fourteen in the same role.
Version2 string
}
Family is a font family the Typst image carries. The runner sets it with Noto behind it for the scripts it lacks.
func Families ¶
func Families() []Family
Families is every family a design may name, in the order an editor offers them. The runner image must carry each one.
func FamilyByName ¶
FamilyByName finds a family by its exact name.
type FieldError ¶
FieldError is a design's refusal: the field, as a dotted path into the document ("fonts.body", "brand.contact.2", "customCover.images.0"; "" for the document as a whole), and what is wrong. The message never quotes the value back, beyond a colour.
func (*FieldError) Error ¶
func (e *FieldError) Error() string
func (*FieldError) Unwrap ¶
func (e *FieldError) Unwrap() error
Unwrap is the refusal's kind, where it has one (ErrImageTooLarge, ErrImageFormat), for errors.Is.
type Fonts ¶
type Fonts struct {
// Headings is any family.
Headings string `json:"headings"`
// Body is a sans or serif family that is not headings-only.
Body string `json:"body"`
// Code is a mono family.
Code string `json:"code"`
}
Fonts names the three faces, each a family of Families.
type Footer ¶
type Footer struct {
PageNumbers string `json:"pageNumbers"`
Slots [SlotCount]string `json:"slots"`
}
Footer is the page footer.
type Header ¶ added in v0.7.4
type Header struct {
// Style is a HeaderStyles value.
Style string `json:"style"`
// Slots are the left, centre and right texts, each a template of
// literal text and tokens (Tokens) of at most MaxLineRunes; "" for an
// empty slot.
Slots [SlotCount]string `json:"slots"`
}
Header is the running header, drawn from page 2 on a report, on every page of a memo and never on a letter.
type Image ¶ added in v0.7.4
type Image struct {
// PNG is the image as a PNG.
PNG string `json:"png,omitempty"`
// JPEG is the image as a JPEG.
JPEG string `json:"jpeg,omitempty"`
}
Image is a design's image in one of the two formats, standard base64 with padding, exactly one of the two set. The zero Image is none.
func NormalizeCoverImage ¶ added in v0.7.4
NormalizeCoverImage turns an uploaded image into a design's cover image, or one of a custom cover's: a PNG or a JPEG (what the bytes are, not what a file name or a header said), at most MaxCoverImageUploadBytes and MaxCoverImageUploadPixels, decoded, scaled down to fit MaxCoverImageSide by averaging, and encoded again from the pixels in the format it came in. A refusal is a *FieldError on field whose kind is ErrImageTooLarge or ErrImageFormat. A JPEG's orientation tag is not read: its pixels are drawn as they are stored.
func NormalizeCustomCoverImage ¶ added in v0.7.4
NormalizeCustomCoverImage turns an uploaded image into one of a custom cover's images, by the cover image's rules (NormalizeCoverImage), named for its place in the list.
func NormalizeThumbnail ¶ added in v0.7.4
NormalizeThumbnail turns an uploaded image into a custom cover's thumbnail: a PNG of at most MaxThumbnailBytes, scaled to fit MaxCoverImageSide, encoded again from its pixels.
type Logo ¶
type Logo struct {
// PNG is the image, standard base64 with padding: a PNG of at most
// MaxLogoBytes and at most MaxLogoSide pixels each way.
PNG string `json:"png"`
}
Logo is a design's logo. The zero Logo is none, and a design without one has no "logo" key.
func NormalizeLogo ¶
NormalizeLogo turns an uploaded image into a design's logo: a PNG or a JPEG (what the bytes are, not what a file name or a header said), at most MaxLogoUploadBytes and MaxLogoUploadPixels, decoded, scaled down to fit MaxLogoSide by averaging, and encoded again as PNG from the pixels. A refusal is a *FieldError on "logo" whose kind is ErrLogoTooLarge or ErrLogoFormat. A JPEG's orientation tag is not read: its pixels are drawn as they are stored.
type Suggestion ¶ added in v0.7.4
type Suggestion struct {
// Accent and Secondary pass TextContrast on white.
Accent, Secondary string
// FromAccent and FromSecondary are the colours as read, before any
// darkening.
FromAccent, FromSecondary string
}
Suggestion is what SuggestColours reads from a logo: its two dominant colours as they are, and the nearest shade of each that passes the contrast rule for text, which passes it for graphics too. Secondary is "" when the logo has one colour.
func SuggestColours ¶ added in v0.7.4
func SuggestColours(logo []byte) (Suggestion, error)
SuggestColours reads the two dominant colours of a logo (its PNG or JPEG bytes, as a design carries them) and offers each as a shade that passes the contrast rule for text: the editors show them for the person to take as the accent and the secondary, never apply them unasked. The logo is held to the logo's upload bounds before a pixel is decoded. Transparent and near-white pixels are the background and are not read; the colour read most is the accent, and the next most that is far enough from it, and at least a twentieth as common, is the secondary.