The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Graphics::Fig - drawing library based on xfig

SYNOPSYS

Objects

arc(radius, angle)

arc(points)

arc({ center => [ xc, yc ], r => length, angle => angle, rotation => rotation, ... })

arc({ center => [ xc, yc ], d => length, angle => angle, rotation => rotation, ... })

arc({ center => [ xc, yc ], point => [ x1, y1 ], angle => angle, ... })

arc({ points => [[ x1, y1 ], [ x3, y3 ]], angle => angle, ... })

arc({ points => [[ x1, y1 ], [ x2, y2 ], [ x3, y3 ]], ... })

arcto(distance, heading, angle)

arcto(points)

arcto({ center => [ xc, yc ], angle => angle, ... })

arcto({ point => [ x3, y3 ], angle => angle, ... })

arcto({ points => [[ x2, y2 ], [ x3, y3 ]], ... })

box(width, height)

box(points)

box({ center => [ xc, yc ], width => width, height => height, ... })

box({ points => [[ x1, y1 ], [ x2, y2 ]], ... })

circle(d)

circle(points)

circle({ center => [ xc, yc ], d => length, ... })

circle({ center => [ xc, yc ], r => length, ... })

circle({ center => [ xc, yc ], point => [ x, y ], ... })

circle({ points => [[ x1, y1 ], [ x2, y2 ], [ x3, y3 ]], ... })

ellipse(a, b)

ellipse(a, b, rotation)

ellipse(points)

ellipse({ center => [ xc, yc ], points => [[ x1, y1 ], [ x2, y2 ]], rotation => rotation, ... })

ellipse({ center => [ xc, yc ], points => [[ x1, y1 ], [ x2, y2 ], [ x3, y3 ]], ... })>

ellipse({ points => [[ x1, y1 ], [ x2, y2 ], [ x3, y3 ], [ x4, y4 ], [ x5, y5 ]], ... })>

lineto(distance, heading)

lineto(points)

lineto({ distance => length, heading => heading, ... })

lineto({ point => [ x2, y2 ], ... })

lineto({ points => [[ x2, y2 ], [ x3, y3 ], ... ], ... })

picture(filename)

picture(filename, width)

picture(filename, width, height)

picture(filename, points)

picture({ filename => filename, width => width, height => height, ... })

picture({ filename => filename, points => [[ x1, y1 ], [ x2, y2 ]], ... })

polygon(n, radius)

polygon(points)

polygon({ center => [ xc, yc ], r => length, rotation => rotation, n => n-sides, ... })

polygon({ center => [ xc, yc ], point => [ x1, y1 ], n => n-sides, ... })

polygon({ points => [[ x1, y2 ], [ x2, y2 ], [ x3, y3 ], ... ], ... })

polyline(points)

polyline({ points => [[ x1, y1 ], [ x2, y2 ], ... ], ... })

spline(points)

spline({ points => [[ x1, y2 ], [ x2, y2 ], [ x3, y3 ], ... ], ... })

splineto(distance, heading)

splineto(points)

splineto(distance => length, heading => heading, ... })

splineto(points => [[ x2, y2 ], [ x3, y3 ], ... ], ... })

text(text)

Control

new({ global-parameters... })

options({ global-parameters... })

begin({ global-parameters... })

end(action)

end({ action => "merge" | "group" | "discard", ... })

moveto(distance, heading)

moveto(point)

moveto({ distance => length, heading => heading, ... })

moveto({ point => [ x, y ], ... })

getposition()

translate(offset)

translate({ offset => [ dx, dy ], ... })

rotate(rotation)

rotate({ rotation => rotation, ... })

scale(scale)

scale({ scale => scale<,> ... })

scale({ scale => [ x-scale, y-scale ], ... })

getbbox()

save(filename)

save({ filename => filename, ... })

export(filename)

export({ filename => filename, ... })

DESCRIPTION

Graphics::Fig is a drawing library that produces xfig save files. This version is based on xfig v3.2.

Simple Example

    my $fig = Graphics::Fig->new();
    $fig->moveto([ 1, 1 ]);
    $fig->lineto([ 4, 1 ]);
    $fig->lineto([ 4, 3 ]);
    $fig->lineto([ 1, 3 ]);
    $fig->lineto([ 1, 1 ]);
    $fig->export("example.pdf");

The first line of the example creates a Fig object and establishes a drawing environment. The moveto command moves the starting position to [ 1, 1 ]. The next four lines draw a rectangle from the starting position. The final line exports the drawing to pdf format.

Parameter Passing

All functions in the library accept named parameters. If the last parameter is a reference to a hash, the hash is interpeted as a set of parameter name / value pairs. In addition, most functions also accept a few positional parameters. For example:

    $fig->lineto([ 3, 2 ]);                             # positional

is equivalent to:

    $fig->lineto({ point => [ 3, 2 ] });                # named

You may mix both positional and named parameters in the same function. For example:

    $fig->lineto([ 3, 2 ], { color => "red" });         # mixed

is equivalent to:

    $fig->lineto({ point => [ 3, 2 ], color => "red" });

This function draws a line segment from the current position to point [ 3, 2 ] using a pen color of red.

Many parameters take default values from the current drawing environment. See Global Parameters.

Functions

new()
new({ global-parameters... })

The new function constructs a new Fig object and establishes the initial drawing environment. All other functions in the library are methods of the Fig object, thus this function must be called first.

The new function accepts an optional list of global parameters that set defaults for other functions (see Global Parameters below).

arc(radius)
arc(radius, angle)
arc(points)

The arc function draws an arc from a starting point, through a control point, to a final point. The arc can be specified in any of the following ways:

center, radius|diameter, angle|Θ, rotation, [controlAngle]

Center and either radius or diameter give the location and size of the associated circle. Angle (alternatively Θ) is the central angle of the arc. Rotation is the angle of the starting point relative to the x-axis.

An optional controlAngle parameter places the control point. If not given, the control point is placed at the midpoint along the arc.

The direction of the arc (clockwise or counterclockwise) is inferred from the sign of angle or can be set explicitly using direction. See parameters below.

center, starting point, angle, [controlAngle]

The starting point can be given instead of radius and rotation.

starting point, final point, angle, [controlAngle]

The starting point and final point can be given instead of center, radius and rotation.

starting point, control point, final point

Starting point, control point and final point uniquely describe the arc.

Parameters

angle|Θ (degrees, default 90)

Angle is the central angle of the arc, i.e. the angle formed by starting point, center and final point.

center = point (default: current position)

Center is the origin of the associated circle. If not given, center defaults to the current position.

controlAngle (degrees, default angle/2)

Control angle is the angle between the starting point and middle point of the arc. The control point appears as a movable point in xfig. If not given, control angle defaults to angle divided by two.

diameter|d = length

Diameter is the diameter of the associated circle. See radius.

direction = "clockwise"|"cw" or "counterclockwise"|"ccw"

Direction specifies whether the arc is drawn counterclockwise or clockwise from the starting point to the final point. If not given, the direction is inferred from the sign of angle, counterclockwise if angle is positive and clockwise if angle is negative. This parameter is particularly useful when using the arrow modes.

points = points

Points specifies one, two or three points along the arc: start, start and final, or start, control and final.

radius|r = length

Radius describes the radius of the associated circle. See diameter.

rotation (degrees)

Rotation is the angle in degrees from the center to the first point relative to the x axis. If neither rotation nor points is given, rotation defaults to zero.

subtype = "open" (default) | "closed"

Subtype selects between a simple arc (open) or a pie wedge, (closed). Closed can alternatively be specified as "pie" or "pie-wedge".

areaFill = areaFill
arrowHeight = length
arrowMode = "none" | "forw[ard]" | "back[ward]" | "both"
arrowStyle
arrowThickness = length
arrowWidth = length
capStyle = "butt" | "round" | "projecting"
color = color
depth = depth
fillColor = color
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

arcto(distance, heading)
arcto(distance, heading, angle)
arcto(points)

The arcto function draws an arc from the current position, through a control point, to a final point then moves the current position to the final point. Arcto can be specified in any of the following ways:

distance, heading, angle, [controlAngle]

Distance and heading describe the final point relative to the current point, where distance is in the current unit and heading is in degrees, with zero aligned on the x-axis. Angle is the central angle of the arc.

The optional controlAngle places the control point. See arc.

Use a positive angle for a counterclockwise arc, a negative angle for a clockwise arc, or specify the direction explicitly using the direction parameter.

center, angle, [controlAngle]

The final point can be calculated from the center of the associated circle and central angle of the arc.

final point, angle, [controlAngle]

The final point can be given directly.

control point, final point

Control point and final point uniquely describe the arc.

Parameters

angle|Θ (degrees, default 90)

Angle is the central angle of the arc, i.e. the angle formed by starting point, center and final point. Angle can alternatively be written as Θ.

center = point

Center is the origin of the associated circle.

controlAngle (degrees, default angle/2)

Control angle is the angle between the starting point and middle point of the arc. This control point appears as a movable point in xfig. If not given, control angle defaults to angle divided by two.

direction = "clockwise"|"cw" or "counterclockwise"|"ccw"

Direction specifies whether the arc is drawn counterclockwise or clockwise from the starting point to the final point. If not given, the direction is inferred from the sign of angle, counterclockwise if angle is positive and clockwise if angle is negative. This parameter is particularly useful when using the arrow modes.

distance = length

Distance is the straight-line distance from the current position to the final point.

heading (degrees)

Heading is the angle in degrees of the final point relative to the current position.

points = points

Points specifies one or two points along the arc: final, or control and final.

subtype = "open" (default) | "closed"

Selects between a simple arc (open) or a pie wedge, (closed). Closed can alternatively be specified as "pie" or "pie-wedge".

areaFill = areaFill
arrowHeight = length
arrowMode = "none" | "forw[ard]" | "back[ward]" | "both"
arrowStyle
arrowThickness = length
arrowWidth = length
capStyle = "butt" | "round" | "projecting"
color = color
depth = depth
fillColor = color
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

begin({ global-parameters })

The begin function pushes a new empty drawing context with given global parameters. Any parameters not specified default to the values in the parent drawing context. See end.

Drawing contexts are useful for drawing a series of objects with shared default parameters and for creating groups.

end()
end(action)

The end function leaves a drawing context started by a matching begin. Based on the given action, objects created within the sub-context are either merged into the parent context, grouped and added to the parent context or discarded. The default action is "merge".

Parameters

action = merge | group | discard

An action of merge (default) merges all objects created in the sub-environment into the parent environment. An action of group groups the objects and adds the group to the parent environment. An action of discard discards all objects created in the sub-environment. The discard option can be useful if you called save while in the sub-environment.

grid = length

When creating a group, this option expands the corners of the group as needed to snap to a grid of given resolution. If not given, the corners of the group are defined by the bounding box of the contained objects.

position = point
units = units

See Global Parameters.

box(width, height)
box(points)

The box function draws a rectangular box specified by either of:

center, width, height

Center is the central point of the box. Width and height are the dimensions of the box. If not given, center defaults to the current position.

two points

Two opposite corners describe a box.

Parameters

center = point (default: current position)

Center is the central point of the box. If not given, center defaults to the current position.

height = length

Height is the vertical dimension of the box.

width = length

Width is the horizontal dimension of the box.

points

Two points give the locations of a pair of opposite corners of the box.

areaFill = areaFill
color = color
cornerRadius = length
depth = depth
fillColor = color
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

circle(diameter)
circle(points)

The circle function draws a circle described by any of the following:

center, radius|diameter

Center is the origin point of the circle. Radius or alternatively, diameter is the size of the circle. If not given, center defaults to the current position.

center, starting point

Center and a point on the circle can be given instead of radius or diameter. If not given, center defaults to the current position.

first point, second point, third point

Any three non-collinear points uniquely describe a circle.

Parameters

center = point (default: current position)

Center is the origin of the circle. If not given, center defaults to the current position.

diameter|d

Diameter is the diameter of the circle. See radius.

point|points

Points specifies one or three points on the circle: the starting point, or any three non-colinear points.

radius|r

Radius describes the radius of the circle. See diameter.

rotation (degrees)

Rotation is the angle from center to the starting point relative to the x-axis. The starting point appears as a movable point in xfig.

subtype = "radius" | "diameter"

Subtype determines whether xfig describes the circle by center and one control point on the circle (radius), or or by two control points on opposite sides of the circle (diameter). If not given, the subtype is automatically inferred from the other parameters.

areaFill = areaFill
color = color
depth = depth
fillColor = color
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

ellipse(a, b)
ellipse(a, b, rotation)
ellipse(points)

The ellipse function draws an ellipse specified in any of the following ways:

center, a, b, rotation

Center, a and b give the origin of the ellipse and the lengths of the two semi axes. Rotation is the angle between the first semi axis and the x axis. If center is not given, it defaults to the current position.

center, two points, rotation

Any two points on the ellipse not colinear with the center can be given instead of the semi axes. If center is not given, center defaults to the current position. If rotation is not given, it defaults to the angle of the first point.

center, three points

Center and any three points on the ellipse not colinear with the center or with each other can be given instead of rotation. If center is not given, it defaults to the current position.

five points

Any five non-colinear points uniquely describe the ellipse.

Parameters

a = length, b = length

The a and b parameters give the lenghts of the two semi axes. While a is normally the major semi axis, it's not an error for it to be smaller than b.

center = point (default: current position)

Center is the origin of the ellipse. If center is not given, it defaults to the current position.

points = points

Points describes two, three or five non-colinear points along the ellipse.

rotation (degrees)

Rotation is the angle of the first axis of the ellipse relative the x axis.

Rotation is the angle from center to the starting point relative to the x-axis. The starting point appears as a movable point in xfig.

subtype = "radii" | "diameters"

Subtype determines whether xfig describes the ellipse by center and the control points of the two semi axes (radii), or by the four control points of the full axes (diameters). If not given, the subtype is automatically inferred from other parameters.

areaFill = areaFill
color = color
depth = depth
fillColor = color
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

export(filename)

The export function exports all objects in the current environment to a given graphics format.

Parameters

exportFormat|format

Specify the output file format, overriding the output filename extension. The list of supported formats depends on version and compile time options of the fig2dev program. Typical supported graphics formats are: "box", "cgm", "dxf" (AutoCAD drawing exchange format), "eepic", "eepicemu", "emf", "epic", "eps", "gbx" (Gerber), "ge", "gif", "ibmgl", "jpeg", "latex", "map" (HTML image map), "mf" (MetaFont), "mmp" (Multi-MetaPost), "mp" (MetaPost), "pcx", "pdf", "pdftex", "pdftex_t", "pic", "pictex", "png", "ppm", "ps", "pstex", "pstex_t", "pstricks", "ptk", "shape" (LaTeX shaped paragraphs), "sld" (AutoCAD slide format), "svg", "textyl", "tiff", "tk", "tpic", "xbm" and "xpm".

exportOptions|options

Provide additional command-line options to the fig2dev program. The value must be a reference to an array of strings. Example: [ "-f", "Roman" ].

filename

Specify the filename of the output file. If the exportFormat option is not given, the type is taken from the filename extension.

comment = string
pageJustification = "Center" | "Flushleft"
magnification = (float, percentage)
multiplePage = "Single" | "Multiple"
orientation = "Landscape" | "Portrait"
paperSize = papersize
position = point
transparentColor = -2 | -1 | color
units = units

See Global Parameters.

getbbox()

The getbbox function returns a reference to an array of two points giving the bounding box for all objects in the current environment. The return value is of the form [ [ x1, y1 ], [ x2, y2 ] ], where [ x1, y1 ] is the top-left corner and [ x2, y2 ] is the bottom right corner.

Parameters

units = units

See Global Parameters.

getposition()

The getposition function returns the current position in the current unit. The return value is a reference to an array of two scalars, [ x, y ]. This array is a copy of the internal position and the caller may modify the returned point without affecting the library.

Parameters

units = units

See Global Parameters.

lineto(distance, heading)
lineto(points)

The lineto function draws a line segment (or series of connected segments) from the current position. Then it moves the current position to the end of the last segment. This object can be given by either of the following:

distance, heading

Distance and heading describe the distance and angle of the next point relative to the current point.

point|points

Given one or more points, the lineto function draws a segment or series of segments passing through each point.

Parameters

distance = length

Distance is the straight-line distance from the current position to the next point.

heading (degrees)

Heading is the angle in degrees of the next point relative to the current position.

new|detachedLineto = boolean

By default, sequences of lineto calls are merged into a single polyline object when possible, i.e. when the position and other parameters are unchanged since the previous call. This behavior is more efficient in terms of number of xfig objects created and it has the benefit of honoring the joinStyle parameter. But when using the arrow modes, it may not be desired because only the final segment receives an arrow.

If the new parameter or global detachedLineto parameter is true, lineto creates a new polyline object even if it could have merged with the previous call. This is useful when using arrow modes.

point|points

One or more points through which the segments should be drawn.

areaFill = areaFill
arrowHeight = length
arrowMode = "none" | "forw[ard]" | "back[ward]" | "both"
arrowStyle
arrowThickness = length
arrowWidth = length
capStyle = "butt" | "round" | "projecting"
color = color
depth = depth
fillColor = color
joinStyle = "miter" | "round" | "bevel"
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

moveto(distance, heading)
moveto(points)

The moveto function changes the current position. There are two styles:

distance, heading

Distance and heading give the distance and angle of the destination relative to the current position.

point

The new position is given as an absolute point.

Parameters

distance = length

Distance is the distance from the current position to the target position.

heading (degrees)

Heading is the angle in degrees of the target position relative to the current position.

point = point

A single point sets the new absolute position.

position = point

The optional position parameter is sets the current position *before* the moveto function changes it again. When using distance and heading, position overrides the starting point; when using point, position has no effect.

units = units

See Global Parameters.

options({ global-parameters })

The options function sets default options for subsequent functions. See Global Parameters.

picture(filename)
picture(filename, width)
picture(filename, width, height)
picture(points)

The picture function inserts an embedded picture into the drawing. There are several forms:

filename, center
filename, center, width
filename, center, height
filename, center, width, height

Filename is the image to be inserted. Center is the central point of the picture. If not given, center defaults to the current position. If either width or height is given, the picture is scaled, preserving aspect ratio, to fit the given dimension. If both width and height are given, the picture is scaled to fit both, modifying the aspect ratio if needed.

filename, two opposite corners

Two points describing opposite corners may be given in place of center, width and height. The original top-left corner of the image is placed at the first point; original bottom-right corner is placed the second point.

Parameters

center = point (default: current position)

Center is the central point of the picture. If not given, center defaults to the current position.

filename

Filename is the name of the file containing the image. The following formats are accepted: eps, gif, jpeg, pcx, png, ppm, ps, tiff, xbm and xpm.

height = length, width = length

Height scales the image vertically; width scales the image horizontally.

points = points

Two points are the locations of a pair of opposite corners of the object.

resolution = xres [yres] [dpi|dpcm|dpm]

Resolution specifies the resolution of the image in dots per inch, dots per centimeter or dots per meter. You may describe non-square pixels by specifying both xres and yres. If not given, the picture function tries to automatically determine the resolution from the image. If the resolution cannot be determined, it defaults to 100 dpi.

areaFill = areaFill
color = color
depth = depth
fillColor = color
joinStyle = "miter" | "round" | "bevel"
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

polygon(n, radius)
polygon(points)

The polygon function draws a polygon described by any of the following:

center, n, radius, rotation

This form draws an n-sided regular polygon. Center is the central point of the polygon. If not given, center defaults to the current position. Radius is the distance from center to each corner. Rotation is the angle from center to the first point relative to the x axis.

center, n, point

You may specify the first point instead of radius and rotation.

points

This form draws an arbitrary closed polygon passing through each point.

Parameters

center = point (default: current position)

Center is the origin of a regular polygon. If not given, center defaults to the current position.

n

N is the number of sides for a regular polygon.

point|points

One point specifies the location of the first corner of a regular polygon. Three or more points specify the corners of an arbitrary polygon.

radius|r

Radius is the distance from the center to each corner of a regular polygon.

rotation (degrees)

Rotation is the angle from center to the first point of a regular polygon relative to the x axis.

areaFill = areaFill
color = color
depth = depth
fillColor = color
joinStyle = "miter" | "round" | "bevel"
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

polyline(points)

The polyline function draws a sequence of interconnected line segments passing through the given points.

Parameters

points = points

Two or more points specify the segments of the object.

areaFill = areaFill
arrowHeight = length
arrowMode = "none" | "forw[ard]" | "back[ward]" | "both"
arrowStyle
arrowThickness = length
arrowWidth = length
capStyle = "butt" | "round" | "projecting"
color = color
depth = depth
fillColor = color
joinStyle = "miter" | "round" | "bevel"
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

rotate(angle) (degrees)

The rotate function rotates all objects in the current drawing context about the given center by the given angle.

Parameters

center = point

Center is the point about which the objects are rotated. If not given, center defaults to the current position.

rotation (degrees)

Rotation is the number of degrees to rotate the objects. A positive rotation is counterclockwise; a negative rotation is clockwise.

position = point
units = units

See Global Parameters.

save(filename)

The save function saves all objects in the current environment to a file in xfig (.fig) format.

Parameters

filename

Give the filename of the save file. The caller should include the .fig suffix as it is not added automatically.

comment = string
pageJustification = "Center" | "Flushleft"
magnification = (float, percentage)
multiplePage = "Single" | "Multiple"
orientation = "Landscape" | "Portrait"
paperSize = papersize
position = point
transparentColor = -2 | -1 | color
units = units

See Global Parameters.

scale(scale)

The scale function scales all objects relative to the given center or current position.

Parameters

center

Center is the point about which all objects are scaled. If not given, center defaults to the current position.

scale = s | [ u, v ]

Scale is the factor by which objects are scaled. The argument may be either a single value to scale with constant aspect ratio, or a reference to an array of two values to scale x and y with different ratios. In some cases, changing the aspect ratio changes the object type. For example, circles become ellipses.

Note that when changing aspect ration, not all objects can be scaled linearly. For example, when changing the aspect ratio of an arc object, the three control points are scaled as specified, but the object remains an arc, i.e. xfig does not have a representation for a section an an ellipse.

position = point
units = units

See Global Parameters.

spline(points)

The spline function draws a spline described by three or more control points.

Parameters

points

Three or more points are the control points of the spline.

shapeFactor|shapeFactors

When drawing an x-spline (see subtype), you must provide either a single shape factor to be applied to all points, or a vector of shape factors, one entry for each point, to control the smoothness of the curve around the control points. A shape factor of -1.0 is an interpolated spline, 0.0 is a polyline, and +1.0 is an approximated spline. Values closer to zero produce sharper curves; values closer to -1.0 or +1.0 provide smoother curves.

subtype|splineSubtype

The spline object has six subtypes: open-approximated, closed-approximated, open-interpolated, closed-interpolated, open-x and closed-x. The default is "open-approximated".

When using open-x or closed-x, you must include a vector of shapeFactors, one for each control point (see above).

areaFill = areaFill
arrowHeight = length
arrowMode = "none" | "forw[ard]" | "back[ward]" | "both"
arrowStyle
arrowThickness = length
arrowWidth = length
capStyle = "butt" | "round" | "projecting"
color = color
depth = depth
fillColor = color
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

splineto(distance, heading)
splineto(points)

The splineto function draws a spline object, leaving the current position at the final point. The function may be called in either of the following two ways:

distance, heading

Distance and heading give the distance and angle of the next control point relative to the current position.

point|points

Starting at the given position, add the specified control points to the spline.

Note that a valid spline must have at least three control points. If splineto is called only once, giving only two control points, the object becomes a polyline.

Parameters

distance = length

Distance is the straight-line distance from the current position to the next point.

heading (degrees)

Heading is the angle in degrees of the next point relative to the current position.

new = boolean

By default, sequences of splineto calls are merged into a single spline object when possible, i.e. if the position and other parameters are unchanged since the previous call. If the new parameter is true, lineto creates a new spline object even if it could have merged with the previous call. This is useful when using arrow modes.

point|points

Starting at the current position, add the given list of control points to the spline.

shapeFactor|shapeFactors

When drawing an x-spline (see subtype), you must provide either a single shape factor to be applied to all points, or a vector of shape factors, one entry for each point, to control the smoothness of the curve around the control points. A shape factor of -1.0 is an interpolated spline, 0.0 is a polyline, and +1.0 is an approximated spline. Values closer to zero produce sharper curves; values closer to -1.0 or +1.0 provide smoother curves.

subtype|splineSubtype

The spline object has six subtypes: open-approximated, closed-approximated, open-interpolated, closed-interpolated, open-x and closed-x. The default is "open-approximated".

areaFill = areaFill
arrowHeight = length
arrowMode = "none" | "forw[ard]" | "back[ward]" | "both"
arrowStyle
arrowThickness = length
arrowWidth = length
capStyle = "butt" | "round" | "projecting"
color = color
depth = depth
fillColor = color
lineStyle
lineThickness = length
position = point
styleVal = length
units = units

See Global Parameters.

text(text)

Format a line of text at the current position.

Parameters

rotation = rotation (degrees)

Rotate the text relative to the x axis.

text = string

Specify a line of text.

color = color
depth = depth
fontFlags = fontFlags
fontName = fontName
fontSize = fontSize (1/72nd inch)
position = point
textJustification = "left" | "right" | "center"
units = units

See Global Parameters.

translate(offset)

The translate function translates all objects in the current drawing context by the given [ dx, dy ] offset.

Parameters

offset = [ dx, dy ]

Specify the change in each dimension. Both dx and dy are of type length (see length below).

position = point
units = units

See Global Parameters.

Global Parameters

The new, options and begin functions take the following global parameters. These parameters provide defaults for subsequent functions.

areaFill (default "not-filled")

Set the area fill pattern (also see fillColor). Valid values are: "not-filled", "black", "shade1" .. "shade19", "tint1" .. "tint19", "full" (in fill color), "white", "left-diagonal-30", "right-diagonal-30", "crosshatch-30", "left-diagonal-45", "right-diagonal-45", "crosshatch-45", "horizontal-bricks", "vertical-bricks", "horizontal-lines", "vertical-lines", "crosshatch", "horizontal-right-shingles", "horizontal-left-shingles", "vertical-descending-shingles", "vertical-ascending-shingles", "fish-scales", "small-fish-scales", "circles", "hexagons", "octagons", "horizontal-tire-treads", "vertical-tire-treads".

arrowHeight = length (default 0.1 inch)

Set the height of arrows (see arrowMode). Alternatively, fArrowHeight and bArrowHeight set the height for only forward arrows or only backward arrows, respectively.

arrowMode = "none" (default) | "forw[ard]" | "back[ward]" | "both"

Draw arrows on arc, arcto, lineto, polyline, spline and splineto figures.

arrowStyle (default "stick")

Set the style for arrows (see arrowMode). Valid values are: "stick", "triangle", "filled-triangle", "indented", "filled-indented", "pointed", "filled-pointed", "diamond", "filled-diamond", "circle", "filled-circle", "goblet", "filled-goblet", "square", "filled-square", "reverse-triangle", "filled-reverse-triangle", "left-indented", "right-indented", "half-triangle", "filled-half-triangle", "half-indented", "filled-half-indented", "half-pointed", "filled-half-pointed", "y", "t", "goal", "gallows", "[ m, n ]",

Alternatively, fArrowStyle and bArrowStyle set the style for only forward arrows or only backward arrows, respectively.

arrowThickness = length (default 0.0125 inch)

Set the thickness of arrow lines. Used with arrowMode. Alternatively, fArrowThickness and bArrowThickness set the thickness for only forward arrows or only backward arrows, respectively.

arrowWidth = length (default 0.05 inch)

Set the width of arrows. Used with arrowMode. Alternatively, fArrowWidth and bArrowWidth set the arrow width for only forward arrows or only backward arrows, respectively.

capStyle = "butt" (default) | "round" | "projecting"

Set the endcap style for arc, arcto, lineto, polyline, spline, and splineto.

color = color (default "black")

Set the default pen color for all objects.

comment = string

Set the comment string that appears in the header of the .fig file.

cornerRadius = length

Set the default corner radius for box objects.

depth = depth (default 50)

Set the default layer for all objects. Valid values are 0..999.

detachedLineto = boolean (default "false")

Don't merge adjacent segments of lineto objects. This option is useful when using the arrow modes to show an arrow to every segment.

exportFormat

Specify the output file format, overriding the output filename extension. The list of supported formats depends on version and compile time options of the fig2dev program. Typical supported graphics formats are: "box", "cgm", "dxf" (AutoCAD drawing exchange format), "eepic", "eepicemu", "emf", "epic", "eps", "gbx" (Gerber), "ge", "gif", "ibmgl", "jpeg", "latex", "map" (HTML image map), "mf" (MetaFont), "mmp" (Multi-MetaPost), "mp" (MetaPost), "pcx", "pdf", "pdftex", "pdftex_t", "pic", "pictex", "png", "ppm", "ps", "pstex", "pstex_t", "pstricks", "ptk", "shape" (LaTeX shaped paragraphs), "sld" (AutoCAD slide format), "svg", "textyl", "tiff", "tk", "tpic", "xbm" and "xpm".

exportOptions

Provide additional command-line options to the fig2dev program. The value must be a reference to an array of strings. Example: [ "-f", "Roman" ].

fillColor = color (default "white")

Set the default fill color when using areaFill.

fontFlags

Set or clear miscellaneous text modifier flags. Use +flagName to set the flag, or -flagName to clear the flag.

[+-]rigid

If the rigid flag is on, the font size does not scale when a compound object is scaled.

[+-]special

If the special text flag is on, special characters such as backslash are passed unmodified to the output when exporting. This option is useful when embedding LaTeX control sequences in the text.

[+-]hidden

If the hidden flag is on, the string "<<>>" is displayed on the canvas instead of the text itself. The text is displayed as usual when printing or exporting.

fontName

Valid values are the following LaTeX fonts: "Default", "Roman", "Bold", "Italic", "Sans Serif" or "Typewriter", or the PostScript fonts: "Postscript Default", "Times Roman", "Times Italic", "Times Bold", "Times Bold Italic", "Avantgarde Book", "Avantgarde Book Oblique", "Avantgarde Demi", "Avantgarde Demi Oblique", "Bookman Light", "Bookman Light Italic", "Bookman Demi", "Bookman Demi Italic", "Courier", "Courier Oblique", "Courier Bold", "Courier Bold Oblique", "Helvetica", "Helvetica Oblique", "Helvetica Bold", "Helvetica Bold Oblique", "Helvetica Narrow", "Helvetica Narrow Oblique", "Helvetica Narrow Bold", "Helvetica Narrow Bold Oblique", "New Century Schoolbook Roman", "New Century Schoolbook Italic", "New Century Schoolbook Bold", "New Century Schoolbook Bold Italic", "Palatino Roman", "Palatino Italic", "Palatino Bold", "Palatino Bold Italic", "Symbol", "Zapf Chancery Medium Italic", "Zapf Dingbats".

fontSize

Set the font size in 1/72nd's of an inch.

grid = length

Set an optional snap-to grid for groups. Causes the corners of groups (see end) to be rounded outward to the next multiple of this length.

joinStyle = "miter" (default) | "round" | "bevel"

Set the segment join style for polyline and lineto.

pageJustification = "Center" (default) | "Flushleft"

Control how fig objects are positioned on a printed page.

lineStyle

Set the default line style. Valid values are: "default", "solid" (default), "dashed", "dotted", "dash-dotted", "dash-double-dotted", "dash-triple-dotted".

lineThickness = length (default "0.0125 inch")

Set the default thickness for all lines.

magnification = (float, percentage, default 100)

Set the printing magnification in percent.

multiplePage = "Single" (default) | "Multiple"

Select whether to print on a single page or multiple pages.

orientation = "Landscape" (default) | "Portrait"

Set the paper orientation or printing.

paperSize (default "Letter")

Set the paper size for printing. Valid values are: "Letter", "Legal", "Ledger", "Tabloid", "A", "B", "C", "D", "E", "A0", "A1", "A2", "A3", "A4", "B5".

position = point (default [0, 0])

Set the starting position. This option has the same effect as using moveto to set the position.

splineSubtype (default "open-approximated")

Set the default subtype for spline and splineto. Valid values are: "open-approximated", "closed-approxmated", "open-interpolated", "closed-interpolated", "open-x", "closed-x".

styleVal = length (default "0.075 inch")

Set the spacing for dashed lines. See lineStyle.

textJustification|justification

Set the text justification. Valid values are: "left", "center" and "right".

transparentColor = -2 (default) | -1 | color

Set the transparent color for GIF export. The special value -2 indicates "none", and the special value -1 indicates background.

units = units (default "1.0 inch")

Set the default unit of length for all length values. If no number is given, it defaults to 1.0.

Common Parameter Types

boolean
true | 1
false | 0
color

Any of the xfig built-in colors: default, black, blue, green, cyan, red, magenta, yellow, white, blue4, blue3, blue2, ltblue, green4, green3, green2, cyan4, cyan3, cyan2, red4, red3, red2, magenta4, magenta3, magenta2, brown4, brown3, brown2, pink4, pink3, pink2, pink, gold, any color supported by Graphics::ColorNames, or a hexadecimal color code #XXXXXX

length

a number followed by optional unit (see units)

point

[ x, y ] where x and y are of type length

points

[[ x1, y1 ], [ x2, y2 ], [ x3, y3 ], ... ]

where xi, yi are of type length. Except for the case of the interpolated spline, the outline of the figure always passes through all points.

units

an optional number followed by one of:

ft | foot | feet:

foot

in | inch | inches:

inch

mil:

1/1000 inch

pt | point:

0.0125 inch

m | meter | metre:

meter

dam | dekameter | dekametre:

10^-1 meter

cm | centimeter | centametre

10^-2 meter

mm | millimeter | millimetre

10^-3 meter

fig:

1200 fig units per inch (imperial mode), or 450 fig units per cm (metric mode)

LICENSE

This module is free software: you can redistribute it and/or modify it under the terms of the Artistic License version 2.0 or later.

AUTHOR

Scott Guthridge <scott_guthridge@rompromity.net>

SEE ALSO

xfig, fig2dev