Notes on a general 2D API

Introduction and Motivation

There is a need for a high-level Go API for developers and designers to think in terms of high level objects that make up a visual display. The objects will be familiar to anyone using a modern illustration program (text, images, lines, arcs, circles, curves, etc). The API should facilitate the artful arrangement of these elements on a scalable 2D canvas.

The principle is to keep the number of methods small and consistent, using a common set of arguments for location (x, y), and dimentions (w, h).

Coordinate System

The coordinate system follows the traditional convention you learned in school: x increasing to the left and y increasing from bottom to top. To simplify, the coordinate system uses percentages ranging from (0-100).

For example:

(0,0) is the origin (lower left)
(0,100) is the upper left
(100,0) is the lower right
(100, 100) is the lower right
(50,50) is middle of the canvas

Text

The text methods place text at any coordinate, where the Y is the baseline. Text strings are Unicode, encoded in UTF-8.

Text attributes include:

Font
Color
Size
Alignment (beginning, centered, end)

There should also me a method to return the width of a string, given a font and size.

Graphics

Each method uses x, y to specify the placement on the coordinate system, and w, h are used to designate the dimensions where applicable.

Ellipse -- centered at (x,y), sized at (w,h)
Rect
Polygon
Line
Arc -- centered at the specified location, sized at (w, h), stroked from angle1, to angle2
Curve -- quadratic Bezier curve

Note that Square and Circle may be constructed from the more general Rect and Ellipse (using equal width and height). Also, if needed, a Polyline method may be constructed using Lines. In the case of Ellipse an Rectangle, the (x, y) coordinates may specify either the center of the object, or its upper left.

Line, Arc, Curve specify a stroke color and stroke width. Ellipse, Rect and Polygon have a filled color, and are optionally stroked.

Image

Image may be placed at any (x,y) location, using a specified width, and height. A scaling factor (0-100) and opacity (0-100) may also be applied.

Color and opacity

Colors may be specified as:

RGBA (red, green, blue, alpha)
SVG named colors (for example "red", "green", "steelblue")

Opacity may be used, ranging from 0 (not visible) to 100 (full opaque)

Transformations

Text and graphics elements may be altered according to:

Translation in either the x, y direction or some combination
Scale (0-100)
Rotation (in degrees).

Data Types

Both the coordinate system (x, y) and dimensions (width, height, sizes, scaling, opacity, stroke width) are expressed as floating point numbers ranging from 0.0 to 100.0. Degrees of rotation and scale factors are also floating point. The red, green, blue and alpha components of colors are integers ranging from 0-255. Font names and optionally colors are expressed as strings.

Methods

Text         (x, y, s, font, color, size, alignment)
Image        (name, x, y, w, h, scale)
Line         (x1, y1, x2, y2,           strokecolor, strokewidth)
Arc          (x1, y1, angle1, angle2,   strokecolor, strokewidth)
Curve        (bx, by, cx, cy, ex, ey,   strokecolor, strokewidth)
Ellipse      (x, y, w, h,               fillcolor, strokecolor, strokewidth)
Rect         (x, y, w, h,               fillcolor, strokecolor, strokewidth)
Polygon      (x, y,                     fillcolor, strokecolor, strokewidth)

Square       (x, y, w,                  fillcolor, strokecolor, strokewidth)
Circle       (x, y, r,                  fillcolor, strokecolor, strokewidth)

Rotate(degrees)
Translate(x, y)
Scale(f)
TextWidth(s string, font, size) float64

ajstarks/2dapi.md