A form batch is a vectorized form with n primitives transformed into a simpler representation: one primitive repositioned n times.

On certain backends this leads to more efficient drawing. For example, SVG can be shortened by using <def> and <use> tags, and raster graphics can render the form primitive to a back buffer and blit it into place for faster drawing.

Batching is an optimization transform that happens at draw time. There's currently no mechanism to manually batch. E.g. contexts cannot have FormBatch children.

Mirror(θ, x, y)

Mirror line passing through point (x,y) at angle θ (in radians).

Mirror(θ)

Mirror(θ)=Mirror(θ, 0.5w, 0.5h)

PGF([output::Union{IO,AbstractString}], width=√200cm, height=10cm, only_tikz=false; texfonts=false) -> Backend

Create a Portable Graphics Format backend. The output is normally passed to draw. Specify a filename using a string as the first argument. If only_tikz is true then the output is a "tikzpicture", otherwise the output is a complete latex document with headers and footers. If texfonts is false, include "\usepackage{fontspec}" in the headers.

Examples

c = compose(context(), rectangle())
draw(PGF("myplot.tex", 10cm, 5cm, true, texfonts=true), c)

Rotation(θ, x, y)

Rotate all forms in context around point (x,y) by angle θ in radians.

Rotation(θ)

Rotation(θ)=Rotation(θ, 0.5w, 0.5h)

SVG([output::Union{IO,AbstractString}], width=√200cm, height=10cm, jsmode=:none) -> Backend

Create a Scalable Vector Graphic backend. The output is normally passed to draw. Specify a filename using a string as the first argument. jsmode can be one of :none, :embed, :linkabs, or :linkrel. See also SVGJS.

Examples

c = compose(context(), line())
draw(SVG("myplot.svg"), c)

Shear(s, θ, x, y)

Shear line passing through point (x,y) at angle θ (in radians), with shear s.

Shear(s, θ)

Shear(s, θ)=Shear(s, θ, 0.5w, 0.5h)

UnitBox(x0, y0, width, height; leftpad=0mm, rightpad=0mm, toppad=0mm, bottompad=0mm)

Specifies the coordinate system for a context, with origin x0, y0, plus width, height.

UnitBox(width, height; leftpad=0mm, rightpad=0mm, toppad=0mm, bottompad=0mm)

Specifies the coordinate system for a context, with origin 0, 0 plus width, height.

UnitBox() = UnitBox(0.0, 0.0, 1.0, 1.0)

fill(cs::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

fill(c)

Define a fill color, where c can be a Colorant or String.

PDF([output::Union{AbstractString, IO}], width=√200cm, height=10cm; dpi=72) -> Backend

Create a Portable Document Format backend. The output is normally passed to draw. Specify a filename using a string as the first argument. Depends on Cairo.jl.

Examples

using Cairo
c = compose(context(), circle())
draw(PDF("myplot.pdf", 10cm, 5cm, dpi=250), c)

The Cairo and Fontconfig packages are necessary for saving as PDF. Add them with the package manager if necessary, then run import Cairo, Fontconfig before invoking PDF.

PNG([output::Union{AbstractString, IO}], width=√200cm, height=10cm; dpi=96) -> Backend

Create a Portable Network Graphics backend. The output is normally passed to draw. Specify a filename using a string as the first argument. Depends on Cairo.jl.

Examples

using Cairo
c = compose(context(), circle())
draw(PNG("myplot.png", 10cm, 5cm, dpi=250), c)

The Cairo and Fontconfig packages are necessary for saving as PNG. Add them with the package manager if necessary, then run import Cairo, Fontconfig before invoking PNG.

PS([output::Union{AbstractString, IO}], width=√200cm, height=10cm; dpi=72) -> Backend

Create a Postscript backend. The output is normally passed to draw. Specify a filename using a string as the first argument. Depends on Cairo.jl.

Examples

using Cairo
c = compose(context(), circle())
draw(PS("myplot.ps", 10cm, 5cm, dpi=250), c)

The Cairo and Fontconfig packages are necessary for saving as PS. Add them with the package manager if necessary, then run import Cairo, Fontconfig before invoking PS.

SVGJS([output::Union{IO,AbstractString}], width=√200cm, height=10cm, jsmode=:embed) -> Backend

Create a Scalable Vector Graphic backend that enables Gadfly's interactivity (pan, zoom, etc.). The default jsmode splices the requisite javascript directly into the output. One can alternatively link to identical external javascript with :linkabs and :linkrel. The output is normally passed to draw. Specify a filename using a string as the first argument. See also SVG.

arc(xs::AbstractVector, ys::AbstractVector, rs::AbstractVector, θ1s::AbstractVector, θ2s::AbstractVector, sectors::AbstractVector)

Arguments can be passed in arrays in order to perform multiple drawing operations.

arc(x, y, r, θ1, θ2, sector)

Define an arc with its center at (x,y), radius of r, between θ1 and θ2. sector (optional) is true or false, true for a pie sector, false for an arc. Arcs are drawn clockwise from θ1 to θ2.

arrow(values::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

arrow(value::Bool)

`arrow()` is a property of arcs, lines and curves. The color of the arrowhead is the same as `stroke()`, but for svg the results will be browser-dependent.

arrow()

`arrow() = arrow(true)`

Attempt to batch a form. Return a Nothing singleton if the Form could not be batched, and FormBatch object if the original form can be replaced.

bezigon(anchor0::Tuple, sides::Vector{<:Vector{<:Tuple}})

Define a bezier polygon. anchor0 is the starting point as an (x,y) tuple. sides contains Vectors of side points (tuples): each vector has the control point(s) and end point for each side (the end point forms the next starting point). The sides can be linear (1 point), quadratic (2 points) or cubic (3 points).

bezigon(anchors::Vector{Tuple}, polysides=Vector{<:Vector{<:Vector{<:Tuple}}})

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

bitmap(mimes::AbstractArray, datas::AbstractArray, x0s::AbstractArray, y0s::AbstractArray, widths::AbstractArray, heights::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations.

bitmap(mime, data, x0, y0, width, height)

Define a bitmap of size widthxheight with its top left corner at the point (x, y).

Some backends can more efficiently draw forms by batching. If so, they shuld define a similar method that returns true.

circle(xs::AbstractArray, ys::AbstractArray, rs::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations.

circle(x, y, r)

Define a circle with its center at (x,y) and a radius of r.

circle()

Define a circle in the center of the current context with a diameter equal to the width of the context.

clip(point_arrays::AbstractArray...)

Arguments can be passed in arrays in order to perform multiple clipping operations at once.

clip(points::AbstractArray)

clip() is a property. Only forms inside the clip shape will be visible.

compose!(a::Context, b, c, ds...) -> a

Add b, c, and ds to the graphic as children of a.

compose(a::Context, b, c, ds...) -> Context

Add b, c, and ds to the graphic as children of a copy of a.

context(x0=0.0w, y0=0.0h, width=1.0w, height=1.0h;
        units=nothing,
        rotation=nothing, mirror=nothing, shear=nothing,
        withjs=false, withoutjs=false,
        minwidth=nothing, minheight=nothing,
        order=0, clip=false, raster=false) -> Context

Create a node in the tree structure that defines a graphic. Use compose to connect child nodes to a parent node. See also Rotation, Mirror, and Shear.

Arguments

• units: the coordinate system for the context, defined by a UnitBox.
• order: the Z-order of this context relative to its siblings.
• clip: clip children of the canvas by its bounding box if true.
• withjs: ignore this context and everything under it if we are not drawing to the SVGJS backend.
• withoutjs: ignore this context if we are drawing on the SVGJS backend.
• raster: if possible, render this subtree as a bitmap. This requires the Cairo. If Cairo isn't available, the default rendering is used.
• minwidth and minheight: the minimum size needed to be drawn correctly, in millimeters.

Count the number of unique primitives in a property, stopping when max_count is exceeded.

curve(anchor0, ctrl0, ctrl1, anchor1)

Define a bezier curve between anchor0 and anchor1 with control points ctrl0 and ctrl1.

curve(anchor0s::AbstractArray, ctrl0s::AbstractArray, ctrl1s::AbstractArray, anchor1s::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations.

draw(b::Backend, c::Context)

Output the tree-structured graphic in c to the given backend.

Examples

draw(SVGJS("foo.svg"), compose(context(), text(0,0,"foo")))

ellipse(x, y, x_radius, y_radius)

Define an ellipse with its center at (x,y) with radii x_radius and y_radius.

ellipse(xs::AbstractArray, ys::AbstractArray, x_radiuses::AbstractArray, y_radiuses::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations.

ellipse()

Define an ellipse in the center of the current context with x_radius=0.5w and y_radius=0.5h.

Remove and return vector forms and vector properties from the Context.

fillopacity(values::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

fillopacity(value)

Define a fill opacity, where 0≤value≤1. For svg, nested contexts will inherit from parent contexts e.g. (context(), fillopacity(a), (context(), fill(c::String), circle())).

Produce a new array of offsets in which near duplicate values have been removed.

line(point_arrays::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

line(points)

Define a line. points is an array of (x,y) tuples.

ngon(x, y, r, n::Int)

Define a n-sided polygon with its center at (x,y), and radius of r. For an upside-down ngon, use -r.

ngon(xs::AbstractVector, ys::AbstractVector, rs::AbstractVector, ns::AbstractVector{Int})

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

Attempt to transform a tree into an equivalent tree that can more easily be batched.

What this does is look for patterns in which a long vector form is accompanied by a large vector property that has a relatively small number of unique values. If there are n unique values, we can split it into n contexts, each with a shorter vector form and only scalar properties.

points(x::Compose.Form)

Extract points from a Compose.Form

polygon(point_arrays::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

polygon(points)

Define a polygon. points is an array of (x,y) tuples that specify the corners of the polygon.

rectangle(x0, y0, width, height)

Define a rectangle of size widthxheight with its top left corner at the point (x, y).

rectangle(x0s::AbstractArray, y0s::AbstractArray, widths::AbstractArray, heights::AbstractArray)

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

rectangle()

Define a rectangle that fills the current context completely.

sector(xs::AbstractVector, ys::AbstractVector, rs::AbstractVector, θ1s::AbstractVector, θ2s::AbstractVector)

Arguments can be passed in arrays in order to perform multiple drawing operations.

sector(x, y, r, θ1, θ2)

Define a pie sector with its center at (x,y), radius of r, between θ1 and θ2.

star(x, y, r, n::Int, ratio)

Define a n-pointed star with its center at (x,y), outer radius of r, and inner radius equal to r*ratio. For an upside-down star, use -r.

star(xs::AbstractVector, ys::AbstractVector, rs::AbstractVector, ns::AbstractVector{Int}, ratios::AbstractVector{Float64})

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

text(x, y, value [,halign::HAlignment [,valign::VAlignment [,rot::Rotation]]])

Draw the text value at the position (x,y) relative to the current context.

The default alignment of the text is hleft vbottom. The vertical and horizontal alignment is specified by passing hleft, hcenter or hright and vtop, vcenter or vbottom as values for halign and valign respectively.

text(xs::AbstractArray, ys::AbstractArray, values::AbstractArray [,haligns::HAlignment [,valigns::VAlignment [,rots::Rotation]]])

Arguments can be passed in arrays in order to perform multiple drawing operations at once.

xgon(x, y, r, n::Int, ratio)

Define a cross with n arms with its center at (x,y), outer radius of r, and inner radius equal to r*ratio. For an upside-down xgon, use -r.

xgon(xs::AbstractVector, ys::AbstractVector, rs::AbstractVector, ns::AbstractVector{Int}, ratios::AbstractVector{Float64})

Arguments can be passed in arrays in order to perform multiple drawing operations at once.