Drawing on 2D Cameras

Parameters

A 2D camera has two parameters: size and bounds. The size of the camera is the width and height of the resulting image, in pixels. The default size is 512x512 pixels. It is set using the "camera2d <id> resize <width> <height>" command. The bounds defines a viewing rectangle in user space which will be transformed onto the image space. Everything within this rectangle will be visible, while everything outside it will not. The bounds are set using this command: "camera2d <id> bounds <x1> <y1> <x2> <y2>". The x1 and x2 parameters determine the x values in user space that will be projected onto the left and right sides of the image, respectively, while the y1 and y2 project the corresponding y coordinates onto the bottom and top of the image. The default bounds are "-1 -1 1 1", resulting in a two-unit square centered at the origin being visible, with positive values going right and up.

Coordinate Systems

There are three coordinate systems available in a 2D camera: user, image-relative, and image-absolute. The user coordinate system (Shape3D.CS_USER) is where most shapes are typically drawn, and out of which a viewing rectangle is chosen by the camera bounds. The image-relative coordinate system (Shape3D.CS_IMAGE_REL) assigns (0, 0) to the upper left corner of the image and (1, 1) to the lower-right. This allows shapes to be placed in a fixed location relative to the image, which will expand and contract accordingly as the image is resized. Finally, the image-absolute coordinate system (Shape3D.CS_IMAGE_ABS) provides direct access to pixel coordinates on the image, with (0, 0) in the upper left and (width, height) in the lower right. This provides for things that must be positioned at a certain location on the image or of a certain pixel size.

Data Format

Drawing instructions enter the camera in the form of a Collection of Shape2D objects. The data type string for this is, accordingly, "Shape2DCollection". Each Shape2D object describes a single shape to be drawn on the camera. The shape member contains a Shape object describing the shape of the object. This can be any Java2D shape, such as Line2D, Rectangle2D, Ellipse2D, etc. The fill and draw members are booleans specifying if the object is to be filled with color and/or drawn around the edges. The color to fill or draw with is specified by the paint member, of type Paint. If drawing is requested, the stroke member specifies the type of stoke to draw with. It is typically a BasicStroke object specifying the width of the line. If a different type of compositing than normal is desired, this can be specified in the composite with an object of type Composite.

The Shape2D class offers static methods for creating commonly-used objects. These include createPoint(x, y), createLine(x1, y1, x2, y2), createRectangle(x1, y1, x2, y2), createEllipse(x1, y1, x2, y2), and createCircle(x, y, radius). They return Shape2D objects initialized with the corresponding Shape, which can then be modified to set the stroke and other parameters.

Shapes can have different coordinate systems for their position and stroke. This is so that, for example, a line can be drawn between two points in user space, but using a stroke of a certain pixel width. The coordinate system for the shape itself is specified by the posCS member variable, while the stroke's coordinate system is in strokeCS. These variables can contain one of the three constants found in Shape2D: CS_USER, CS_IMAGE_REL, and Shape3D.CS_IMAGE_ABS. The default stroke is of width 1 in the image-absolute coordinate system, so that simply creating and positioning a shape will produce a 1-pixel-wide drawing on the image without having to set up the stroke.

Examples

A 1-pixel white point at (0.5, 0.5) in user space:

Shape2D shape = Shape2D.createPoint(0.5, 0.5);
shape.paint = Color.white;

A red line from (0, 0) to (1, 1) in user space with a 1-pixel stroke in image-absolute space:

Shape2D shape = Shape2D.createLine(0, 0, 1, 1);
shape.paint = Color.red;

A red line from (0, 0) to (1, 1) in user space with a 5-pixel stroke in image-absolute space:

Shape2D shape = Shape2D.createLine(0, 0, 1, 1);
shape.stroke = new BasicStroke(5);
shape.paint = Color.red;

A red line from (0, 0) to (1, 1) in user space with an 0.05-unit stroke in user space:

Shape2D shape = Shape2D.createLine(0, 0, 1, 1);
shape.stroke = new BasicStroke(0.05);
shape.strokeCS = Shape2D.CS_USER;
shape.paint = Color.red;

A unit rectangle outline from (0, 0) to (1, 1) in user space with a 1-pixel blue stroke in image-absolute space:

Shape2D shape = Shape2D.createRectangle(0, 0, 1, 1);
shape.paint = Color.blue;

A rectangle enclosing the center of the image, from (0.25, 0.25) to (0.75, 0.75) in image-relative space, with an 0.05-unit blue stroke in image-relative space:

Shape2D shape = Shape2D.createRectangle(0.25, 0.25, 0.75, 0.75);
shape.posCS = Shape2D.CS_IMAGE_REL;
shape.stroke = new BasicStroke(0.05);
shape.strokeCS = Shape2D.CS_IMAGE_REL;
shape.paint = Color.blue;

A blue filled rectangle covering the center of the image, from (0.25, 0.25) to (0.75, 0.75) in image-relative space:

Shape2D shape = Shape2D.createRectangle(0.25, 0.25, 0.75, 0.75);
shape.posCS = Shape2D.CS_IMAGE_REL;
shape.fill = true;
shape.draw = false;
shape.paint = Color.blue;

-- TimPeterson - 12 Jun 2006