graphics

package
v0.4.5 Latest Latest
Warning

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

Go to latest
Published: Mar 26, 2024 License: GPL-3.0 Imports: 13 Imported by: 1

Documentation

Overview

Package graphics allows to write PDF content streams.

The main functionality of this package is provided by the Writer type. New Writer objects are created using the NewWriter function. The methods of the Writer type allow to write PDF content streams. Errors are reported using the `Writer.Err` field. Once an error has been reported, all writer methods will return immediately without doing anything.

The following code illustrates how to use a Writer to draw a red square with a black outline:

out := &bytes.Buffer{}
w := graphics.NewWriter(out, pdf.V2_0)

w.SetLineWidth(2)
w.SetFillColor(color.DeviceRGB.New(1, 0, 0))
w.Rectangle(100, 100, 200, 200)
w.FillAndStroke()

if w.Err != nil {
	log.Fatal(w.Err)
}
// The content stream is now in the buffer "out".
// The corresponding resources dictionary is in w.Resources.

Index

Constants

Variables

This section is empty.

Functions

This section is empty.

Types

type ExtGState added in v0.4.0

type ExtGState struct {
	pdf.Res
	Value State
}

ExtGState represents a combination of graphics state parameters. This combination of parameters can be set using the Writer.SetExtGState method.

Note that not all graphics parameters can be set using the ExtGState object. In particular, the stroke and fill color and some text parameters cannot be included in the ExtGState object.

func NewExtGState added in v0.4.0

func NewExtGState(s State, defaultName pdf.Name) (*ExtGState, error)

NewExtGState creates a new ExtGState object.

If s contains values for parameters that cannot be included in an ExtGState object, an error is returned.

func (*ExtGState) Embed added in v0.4.0

func (s *ExtGState) Embed(w pdf.Putter) (*ExtGState, error)

Embed writes the graphics state dictionary into the PDF file so that the graphics state can refer to it by reference. This can reduce the PDF file size if the graphics state is shared between multiple content streams.

type LineCapStyle

type LineCapStyle uint8

LineCapStyle is the style of the end of a line.

const (
	LineCapButt   LineCapStyle = 0
	LineCapRound  LineCapStyle = 1
	LineCapSquare LineCapStyle = 2
)

Possible values for LineCapStyle. See section 8.4.3.3 of PDF 32000-1:2008.

type LineJoinStyle

type LineJoinStyle uint8

LineJoinStyle is the style of the corner of a line.

const (
	LineJoinMiter LineJoinStyle = 0
	LineJoinRound LineJoinStyle = 1
	LineJoinBevel LineJoinStyle = 2
)

Possible values for LineJoinStyle.

type MarkedContent added in v0.4.1

type MarkedContent struct {
	Properties pdf.Dict
	Tag        pdf.Name
	Inline     bool
	DefName    pdf.Name
}

MarkedContent represents a marked-content point or sequence.

func (*MarkedContent) DefaultName added in v0.4.1

func (mc *MarkedContent) DefaultName() pdf.Name

DefaultName implements the pdf.Resource interface.

func (*MarkedContent) PDFObject added in v0.4.1

func (mc *MarkedContent) PDFObject() pdf.Object

PDFObject implements the pdf.Resource interface.

type Parameters added in v0.4.0

type Parameters struct {
	// CTM is the "current transformation matrix", which maps positions from
	// user coordinates to device coordinates.
	// (default: device-dependent)
	CTM matrix.Matrix

	StartX, StartY     float64 // the starting point of the current path
	CurrentX, CurrentY float64 // the "current point"

	StrokeColor color.Color
	FillColor   color.Color

	// Text State parameters:
	TextCharacterSpacing  float64 // character spacing (T_c)
	TextWordSpacing       float64 // word spacing (T_w)
	TextHorizontalScaling float64 // horizonal scaling (T_h, normal spacing = 1)
	TextLeading           float64 // leading (T_l)
	TextFont              font.Embedded
	TextFontSize          float64
	TextRenderingMode     TextRenderingMode
	TextRise              float64
	TextKnockout          bool

	// See https://github.com/pdf-association/pdf-issues/issues/368
	TextMatrix     matrix.Matrix // reset at the start of each text object
	TextLineMatrix matrix.Matrix // reset at the start of each text object

	LineWidth   float64
	LineCap     LineCapStyle
	LineJoin    LineJoinStyle
	MiterLimit  float64
	DashPattern []float64
	DashPhase   float64

	RenderingIntent RenderingIntent

	// StrokeAdjustment is a flag specifying whether to compensate for possible
	// rasterization effects when stroking a path with a line width that is
	// small relative to the pixel resolution of the output device.
	StrokeAdjustment bool

	BlendMode              pdf.Object
	SoftMask               pdf.Object
	StrokeAlpha            float64
	FillAlpha              float64
	AlphaSourceFlag        bool
	BlackPointCompensation pdf.Name

	OverprintStroke bool
	OverprintFill   bool // for PDF<1.3 this must equal OverprintStroke
	OverprintMode   int  // for PDF<1.3 this must be 0

	BlackGeneration   pdf.Object
	UndercolorRemoval pdf.Object
	TransferFunction  pdf.Object
	Halftone          pdf.Object
	HalftoneOriginX   float64 //  https://github.com/pdf-association/pdf-issues/issues/260
	HalftoneOriginY   float64

	// FlatnessTolerance is a positive number specifying the precision with which
	// curves are be rendered on the output device.  Smaller numbers give
	// smoother curves, but also increase the amount of computation needed
	// (default: 1).
	FlatnessTolerance float64

	// SmoothnessTolerance is a number in the range 0 to 1 specifying the
	// precision of smooth shading (default: device-dependent).
	SmoothnessTolerance float64
}

Parameters collects all graphical parameters of the PDF processor.

See section 8.4 of PDF 32000-1:2008.

func (*Parameters) Clone added in v0.4.0

func (p *Parameters) Clone() *Parameters

Clone returns a shallow copy of the parameter vector.

type RenderingIntent added in v0.4.1

type RenderingIntent pdf.Name

A RenderingIntent specifies the PDF rendering intent.

See section 8.6.5.8 of ISO 32000-2:2020.

const (
	AbsoluteColorimetric RenderingIntent = "AbsoluteColorimetric"
	RelativeColorimetric RenderingIntent = "RelativeColorimetric"
	Saturation           RenderingIntent = "Saturation"
	Perceptual           RenderingIntent = "Perceptual"
)

The PDF standard rendering intents.

type Shading added in v0.4.2

type Shading struct {
	pdf.Res
}

Shading represents a PDF shading dictionary.

Shadings can either be drawn to the page using the Writer.DrawShading method, or can be used as the basis of a shading pattern.

type State added in v0.3.5

type State struct {
	*Parameters
	Set StateBits
}

State represents the graphics state of a PDF processor.

func NewState added in v0.3.5

func NewState() State

NewState returns a new graphics state with default values, and a bit mask indicating which fields are set to their default values.

func (State) ApplyTo added in v0.4.1

func (s State) ApplyTo(w *Writer)

ApplyTo calls methods of the Writer to set the graphics state to the state described by s.

func (State) CopyTo added in v0.4.3

func (s State) CopyTo(other *State)

CopyTo applies the graphics state parameters to the given state.

func (State) GetTextPositionDevice added in v0.4.0

func (s State) GetTextPositionDevice() (float64, float64)

GetTextPositionDevice returns the current text position in device coordinates.

func (State) TextLayout added in v0.4.3

func (s State) TextLayout(seq *font.GlyphSeq, text string) *font.GlyphSeq

TextLayout appends a string to a GlyphSeq, using the text parameters from the given graphics state. If seq is nil, a new GlyphSeq is allocated. The resulting GlyphSeq is returned. If seq is not nil, the return value is guaranteed to be equal to seq.

If no font is set, or if the current font does not support layouting, the function returns nil.

type StateBits added in v0.4.0

type StateBits uint64

StateBits is a bit mask for the fields of the State struct.

const (
	StateStrokeColor StateBits = 1 << iota
	StateFillColor

	StateTextCharacterSpacing
	StateTextWordSpacing
	StateTextHorizontalScaling
	StateTextLeading
	StateTextFont // includes size
	StateTextRenderingMode
	StateTextRise
	StateTextKnockout

	StateTextMatrix // text matrix and text line matrix

	StateLineWidth
	StateLineCap
	StateLineJoin
	StateMiterLimit
	StateLineDash // pattern and phase

	StateRenderingIntent
	StateStrokeAdjustment
	StateBlendMode
	StateSoftMask
	StateStrokeAlpha
	StateFillAlpha
	StateAlphaSourceFlag
	StateBlackPointCompensation

	StateOverprint
	StateOverprintMode
	StateBlackGeneration
	StateUndercolorRemoval
	StateTransferFunction
	StateHalftone
	StateHalftoneOrigin
	StateFlatnessTolerance
	StateSmoothnessTolerance

	AllStateBits = stateFirstUnused - 1
)

Possible values for StateBits.

type TextRenderingMode added in v0.4.0

type TextRenderingMode uint8

TextRenderingMode is the rendering mode for text.

const (
	TextRenderingModeFill TextRenderingMode = iota
	TextRenderingModeStroke
	TextRenderingModeFillStroke
	TextRenderingModeInvisible
	TextRenderingModeFillClip
	TextRenderingModeStrokeClip
	TextRenderingModeFillStrokeClip
	TextRenderingModeClip
)

Possible values for TextRenderingMode. See section 9.3.6 of ISO 32000-2:2020.

type Writer added in v0.4.0

type Writer struct {
	Version   pdf.Version
	Content   io.Writer
	Resources *pdf.Resources
	Err       error

	State
	// contains filtered or unexported fields
}

Writer writes a PDF content stream.

func NewWriter added in v0.4.0

func NewWriter(w io.Writer, v pdf.Version) *Writer

NewWriter allocates a new Writer object.

func (*Writer) Circle added in v0.4.0

func (w *Writer) Circle(x, y, radius float64)

Circle appends a circle to the current path, as a closed subpath.

This is a convenience function, which uses Writer.MoveTo and Writer.CurveTo to draw the circle.

func (*Writer) ClipEvenOdd added in v0.4.0

func (w *Writer) ClipEvenOdd()

ClipEvenOdd sets the current clipping path using the even-odd rule.

This implements the PDF graphics operator "W*".

func (*Writer) ClipNonZero added in v0.4.0

func (w *Writer) ClipNonZero()

ClipNonZero sets the current clipping path using the nonzero winding number rule.

This implements the PDF graphics operator "W".

func (*Writer) CloseAndStroke added in v0.4.0

func (w *Writer) CloseAndStroke()

CloseAndStroke closes and strokes the current path. This has the same effect as Writer.ClosePath followed by Writer.Stroke.

This implements the PDF graphics operator "s".

func (*Writer) CloseFillAndStroke added in v0.4.1

func (w *Writer) CloseFillAndStroke()

CloseFillAndStroke closes, fills and strokes the current path. This has the same effect as Writer.ClosePath followed by Writer.FillAndStroke.

This implements the PDF graphics operator "b".

func (*Writer) CloseFillAndStrokeEvenOdd added in v0.4.1

func (w *Writer) CloseFillAndStrokeEvenOdd()

CloseFillAndStrokeEvenOdd closes, fills and strokes the current path, using the even-odd rule for filling. This has the same effect as Writer.ClosePath followed by Writer.FillAndStrokeEvenOdd.

This implements the PDF graphics operator "b*".

func (*Writer) ClosePath added in v0.4.0

func (w *Writer) ClosePath()

ClosePath closes the current subpath.

This implements the PDF graphics operator "h".

func (*Writer) CurveTo added in v0.4.0

func (w *Writer) CurveTo(x1, y1, x2, y2, x3, y3 float64)

CurveTo appends a cubic Bezier curve to the current path.

This implements the PDF graphics operators "c", "v", and "y".

func (*Writer) DrawShading added in v0.4.1

func (w *Writer) DrawShading(shading *Shading)

DrawShading paints the given shading, subject to the current clipping path. The current colour in the graphics state is neither used nor altered.

All coordinates in the shading dictionary are interpreted relative to the current user space. The "Background" entry in the shading pattern (if any) is ignored.

This implements the PDF graphics operator "sh".

func (*Writer) DrawXObject added in v0.4.2

func (p *Writer) DrawXObject(obj *XObject)

DrawXObject draws a PDF XObject on the page. This can be used to draw images, forms, or other XObjects.

This implements the PDF graphics operator "Do".

func (*Writer) EndPath added in v0.4.0

func (w *Writer) EndPath()

EndPath ends the path without filling and stroking it. This is for use after the Writer.ClipNonZero and Writer.ClipEvenOdd methods.

This implements the PDF graphics operator "n".

func (*Writer) Fill added in v0.4.0

func (w *Writer) Fill()

Fill fills the current path, using the nonzero winding number rule. Any subpaths that are open are implicitly closed before being filled.

This implements the PDF graphics operator "f".

func (*Writer) FillAndStroke added in v0.4.0

func (w *Writer) FillAndStroke()

FillAndStroke fills and strokes the current path. Any subpaths that are open are implicitly closed before being filled.

This implements the PDF graphics operator "B".

func (*Writer) FillAndStrokeEvenOdd added in v0.4.1

func (w *Writer) FillAndStrokeEvenOdd()

FillAndStrokeEvenOdd fills and strokes the current path, using the even-odd rule for filling. Any subpaths that are open are implicitly closed before being filled.

This implements the PDF graphics operator "B*".

func (*Writer) FillEvenOdd added in v0.4.0

func (w *Writer) FillEvenOdd()

FillEvenOdd fills the current path, using the even-odd rule. Any subpaths that are open are implicitly closed before being filled.

This implements the PDF graphics operator "f*".

func (*Writer) LineTo added in v0.4.0

func (w *Writer) LineTo(x, y float64)

LineTo appends a straight line segment to the current path.

This implements the PDF graphics operator "l".

func (*Writer) LineToArc added in v0.4.0

func (w *Writer) LineToArc(x, y, radius, startAngle, endAngle float64)

LineToArc appends a circular arc to the current subpath, connecting the previous point to the arc using a straight line.

This is a convenience function, which uses Writer.LineTo and Writer.CurveTo to draw the arc.

func (*Writer) MarkedContentEnd added in v0.4.1

func (w *Writer) MarkedContentEnd()

MarkedContentEnd ends a marked-content sequence. This must be matched with a preceding call to Writer.MarkedContentStart.

func (*Writer) MarkedContentPoint added in v0.4.1

func (w *Writer) MarkedContentPoint(mc *MarkedContent)

MarkedContentPoint adds a marked-content point to the content stream.

The tag parameter specifies the role or significance of the point. The properties parameter is a property list. Properties can either be nil, or a pdf.Dict, or a pdf.Resource representing a pdf.Dict.

This implements the PDF graphics operators "MP" and "DP".

func (*Writer) MarkedContentStart added in v0.4.1

func (w *Writer) MarkedContentStart(mc *MarkedContent)

MarkedContentStart begins a marked-content sequence. The sequence is terminated by a call to Writer.MarkedContentEnd.

The tag parameter specifies the role or significance of the sequence. The properties parameter is a property list. Properties can either be nil, or a pdf.Dict, or a pdf.Resource representing a pdf.Dict.

This implements the PDF graphics operators "BMC" and "BDC".

func (*Writer) MoveTo added in v0.4.0

func (w *Writer) MoveTo(x, y float64)

MoveTo starts a new path at the given coordinates.

This implements the PDF graphics operator "m".

func (*Writer) MoveToArc added in v0.4.0

func (w *Writer) MoveToArc(x, y, radius, startAngle, endAngle float64)

MoveToArc appends a circular arc to the current path, starting a new subpath.

This is a convenience function, which uses Writer.MoveTo and Writer.CurveTo to draw the arc.

func (*Writer) PopGraphicsState added in v0.4.0

func (w *Writer) PopGraphicsState()

PopGraphicsState restores the previous graphics state.

This implementes the PDF graphics operator "Q".

func (*Writer) PushGraphicsState added in v0.4.0

func (w *Writer) PushGraphicsState()

PushGraphicsState saves the current graphics state.

This implementes the PDF graphics operator "q".

func (*Writer) Rectangle added in v0.4.0

func (w *Writer) Rectangle(x, y, width, height float64)

Rectangle appends a rectangle to the current path as a closed subpath.

This implements the PDF graphics operator "re".

func (*Writer) SetExtGState added in v0.4.0

func (w *Writer) SetExtGState(s *ExtGState)

SetExtGState sets selected graphics state parameters.

This implements the "gs" graphics operator.

func (*Writer) SetFillColor added in v0.4.0

func (w *Writer) SetFillColor(c color.Color)

SetFillColor sets the color to use for non-stroking operations.

func (*Writer) SetFlatnessTolerance added in v0.4.0

func (w *Writer) SetFlatnessTolerance(flatness float64)

SetFlatnessTolerance sets the flatness tolerance.

This implementes the PDF graphics operator "i".

func (*Writer) SetLineCap added in v0.4.0

func (w *Writer) SetLineCap(cap LineCapStyle)

SetLineCap sets the line cap style.

This implementes the PDF graphics operator "J".

func (*Writer) SetLineDash added in v0.4.1

func (w *Writer) SetLineDash(pattern []float64, phase float64)

SetLineDash sets the line dash pattern.

This implementes the PDF graphics operator "d".

func (*Writer) SetLineJoin added in v0.4.0

func (w *Writer) SetLineJoin(join LineJoinStyle)

SetLineJoin sets the line join style.

This implementes the PDF graphics operator "j".

func (*Writer) SetLineWidth added in v0.4.0

func (w *Writer) SetLineWidth(width float64)

SetLineWidth sets the line width.

This implementes the PDF graphics operator "w".

func (*Writer) SetMiterLimit added in v0.4.0

func (w *Writer) SetMiterLimit(limit float64)

SetMiterLimit sets the miter limit.

This implementes the PDF graphics operator "M".

func (*Writer) SetRenderingIntent added in v0.4.0

func (w *Writer) SetRenderingIntent(intent RenderingIntent)

SetRenderingIntent sets the rendering intent.

This implementes the PDF graphics operator "ri".

func (*Writer) SetStrokeColor added in v0.4.0

func (w *Writer) SetStrokeColor(c color.Color)

SetStrokeColor sets the color to use for stroking operations.

func (*Writer) Stroke added in v0.4.0

func (w *Writer) Stroke()

Stroke strokes the current path.

This implements the PDF graphics operator "S".

func (*Writer) TextEnd added in v0.4.0

func (w *Writer) TextEnd()

TextEnd ends the current text object. This must be paired with Writer.TextStart.

This implements the PDF graphics operator "ET".

func (*Writer) TextFirstLine added in v0.4.0

func (w *Writer) TextFirstLine(x, y float64)

TextFirstLine moves to the start of the next line of text.

This implements the PDF graphics operator "Td".

func (*Writer) TextNextLine added in v0.4.0

func (w *Writer) TextNextLine()

TextNextLine moves to the start of the next line of text.

This implements the PDF graphics operator "T*".

func (*Writer) TextSecondLine added in v0.4.0

func (w *Writer) TextSecondLine(dx, dy float64)

TextSecondLine moves to the start of the next line of text and sets the leading to -dy. Usually, dy is negative, to get a positive leading.

This implements the PDF graphics operator "TD".

func (*Writer) TextSetCharacterSpacing added in v0.4.0

func (w *Writer) TextSetCharacterSpacing(charSpacing float64)

TextSetCharacterSpacing sets additional character spacing.

This implementes the PDF graphics operator "Tc".

func (*Writer) TextSetFont added in v0.4.0

func (w *Writer) TextSetFont(font font.Embedded, size float64)

TextSetFont sets the font and font size.

This implements the PDF graphics operator "Tf".

func (*Writer) TextSetHorizontalScaling added in v0.4.0

func (w *Writer) TextSetHorizontalScaling(scaling float64)

TextSetHorizontalScaling sets the horizontal scaling. The effect of this is to strech/compress the text horizontally. The value 1 corresponds to normal scaling. Negative values correspond to horizontally mirrored text.

This implementes the PDF graphics operator "Tz".

func (*Writer) TextSetLeading added in v0.4.0

func (w *Writer) TextSetLeading(leading float64)

TextSetLeading sets the leading. The leading is the distance between the baselines of two consecutive lines of text. Positive values indicate that the next line of text is below the current line.

This implementes the PDF graphics operator "TL".

func (*Writer) TextSetMatrix added in v0.4.0

func (w *Writer) TextSetMatrix(M matrix.Matrix)

TextSetMatrix replaces the current text matrix and line matrix with M.

This implements the PDF graphics operator "Tm".

func (*Writer) TextSetRenderingMode added in v0.4.0

func (w *Writer) TextSetRenderingMode(mode TextRenderingMode)

TextSetRenderingMode sets the text rendering mode.

This implements the PDF graphics operator "Tr".

func (*Writer) TextSetRise added in v0.4.0

func (w *Writer) TextSetRise(rise float64)

TextSetRise sets the text rise. Positive values move the text up.

This implements the PDF graphics operator "Ts".

func (*Writer) TextSetWordSpacing added in v0.4.0

func (w *Writer) TextSetWordSpacing(wordSpacing float64)

TextSetWordSpacing sets additional word spacing.

This implementes the PDF graphics operator "Tw".

func (*Writer) TextShow added in v0.4.0

func (w *Writer) TextShow(s string) float64

TextShow draws a string.

func (*Writer) TextShowAligned added in v0.4.0

func (w *Writer) TextShowAligned(s string, width, q float64)

TextShowAligned draws a string and aligns it. The string is aligned in a space of the given width. q=0 means left alignment, q=1 means right alignment and q=0.5 means centering.

func (*Writer) TextShowGlyphs added in v0.4.0

func (w *Writer) TextShowGlyphs(seq *font.GlyphSeq) float64

TextShowGlyphs shows the PDF string s, taking kerning and text rise into account.

This uses the "TJ", "Tj" and "Ts" PDF graphics operators.

func (*Writer) TextShowKernedRaw added in v0.4.1

func (w *Writer) TextShowKernedRaw(args ...pdf.Object)

TextShowKernedRaw shows an already encoded text in the PDF file, using kerning information provided to adjust glyph spacing.

The arguments must be of type pdf.String, pdf.Real, pdf.Integer or pdf.Number.

This implements the PDF graphics operator "TJ".

func (*Writer) TextShowNextLineRaw added in v0.4.1

func (w *Writer) TextShowNextLineRaw(s pdf.String)

TextShowNextLineRaw start a new line and then shows an already encoded text in the PDF file. This has the same effect as Writer.TextNextLine followed by Writer.TextShowRaw.

This implements the PDF graphics operator "'".

func (*Writer) TextShowRaw added in v0.4.0

func (w *Writer) TextShowRaw(s pdf.String)

TextShowRaw shows an already encoded text in the PDF file.

This implements the PDF graphics operator "Tj".

func (*Writer) TextShowSpacedRaw added in v0.4.1

func (w *Writer) TextShowSpacedRaw(wordSpacing, charSpacing float64, s pdf.String)

TextShowSpacedRaw adjusts word and character spacing and then shows an already encoded text in the PDF file. This has the same effect as Writer.TextSetWordSpacing and Writer.TextSetCharacterSpacing, followed by Writer.TextShowRaw.

This implements the PDF graphics operator '"'.

func (*Writer) TextStart added in v0.4.0

func (w *Writer) TextStart()

TextStart starts a new text object. This must be paired with Writer.TextEnd.

This implements the PDF graphics operator "BT".

func (*Writer) Transform added in v0.4.0

func (w *Writer) Transform(extraTrfm matrix.Matrix)

Transform applies a transformation matrix to the coordinate system. This function modifies the current transformation matrix, so that the new, additional transformation is applied to the user coordinates first, followed by the existing transformation.

This implementes the PDF graphics operator "cm".

type XObject added in v0.4.2

type XObject struct {
	pdf.Res
}

XObject represents a PDF XObject.

Directories

Path Synopsis
Package color implements the PDF color spaces and colors.
Package color implements the PDF color spaces and colors.
Package form implements PDF form XObjects.
Package form implements PDF form XObjects.

Jump to

Keyboard shortcuts

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