coordsys

Context: concepts

Synopsis

ChIPS coordinate systems: pixel, window normalized, frame normalized, plot normalized, and data.

Description

There are five coordinate systems in ChIPS:

Coordinate System	Description	Enumeration
window normalized	the dimensions of the window with min and max values from zero to one	WINDOW_NORM
pixel	the dimensions of the window in pixels	PIXEL
frame normalized	the dimensions of the frame with min and max values from zero to one	FRAME_NORM
plot normalized	the dimensions of the plot area with min and max values from zero to one	PLOT_NORM
data	the range of an x and y axis	DATA

All objects (except for windows) are positioned in a coordinate system. Once an object is added to a coordinate system, it is always associated with that coordinate system. There is no way to change the coordinate system to which an object belongs after it has been created.

For most objects, the coordinate system that will be used is predetermined.

the corners of a frame are defined in window normalized coordinates
the corners of a plot are defined in frame normalized coordinates
the points on a curve are defined in data coordinates
Annotations, which includes color abrs, labels, lines, points and regions, can be defined in any of the five coordinate systems. By default, annotations are added to the lowest coordinate system available to the frame (data, then plot normalized, then frame normalized, etc.).

A coordinate system becomes current and accessible when the object which defines it becomes current and accessible. Only the current coordinate systems are considered when determining the default system.

Creating and Deleting Systems

Coordinate systems are created with the objects which define them.

Window normalized and pixel coordinates are created when a window is created.
Frame normalized is created when a frame is created.
Plot normalized is created when a plot is created.
Data coordinates are created when axes are added to the system. Whenever an axis is created, a data coordinate system is created for each perpendicular axis which exists.

Deleting an object removes the coordinate system and any objects associated with that coordinate system.

Binding

The object becomes bound to the coordinate system in which it is positioned. Adjusting the coordinate system (i.e. changing the boundaries) causes the object position to shift accordingly. For example, a point added to a window normalized coordinate system will be repositioned if the window size changes.

Clipping

A coordinate system may clip an object, e.g. hide the part of the object which falls outside of the coordinate system boundaries. Objects in data coordinates may be clipped at the boundary of the plot area. Objects in any other coordinate system may be clipped at the frame edge.

info_coordinate Command

The info_coordinate command provides a means of seeing what data coordinate systems exist, where they reside, and the ids associated with them. Refer to "ahelp info_coordinate" for complete details.

Converting Between Systems

The convert_coordinate command converts a point from one ChIPS coordinate system to another. The conversion can be performed between any coordinate systems which have been created. For example, the value of a point in data system coordinates can be converted to the data system from a different plot. For more information and examples, refer to "ahelp convert_coordinate".

Using the coordsys attribute

The coordsys attribute which can be used to specify the coordinate system to use when creating an object. As an example, to place a label at the top left of the frame - ie using frame-normalized coordinates - you could say:

add_label(0.05, 0.9, "Label", ["coordsys", FRAME_NORM])

This is an alternative to using the coord_sys field of a ChipsId object.

Using a ChipsId

The ChipsId object allows the user to set or modify the currency of ChIPS objects. It also contains entries to specify coordinate systems and coordinate system ids. The ChipsId is optional and is generally the first parameter in the command. Refer to "ahelp chipsid" for general information on how it is used.

The coord_sys entry in the ChipsId is used to specify the coordinate system to use when adding objects. For instance:

add_axis(XY_AXIS, 0, 0, 10)
id = ChipsId()
id.coord_sys = PLOT_NORM
add_label(id, 0.1, 0.1, "My label")

By default, the label would been added in the data system created by the x and y axis. However, setting the ChipsId's the coord_sys entry to PLOT_NORM causes it to be added in plot normalized coordinates.

The ChipsId also has a coord field, which can be populated with a data system id. When a data system is created, an id string is associated with it. The string is formatted as the plot id, an underscore, and the x axis id and y axis id, e.g. "plot1_ax1ay1".

Both the coord and coord_sys need to be set when adding an annotation to a data system which is not the default.

add_axis(XY_AXIS, 0, 0, 10)
add_axis(XY_AXIS, 0, 0, 1000)
id = ChipsId()
id.coord_sys = DATA
id.coord = "plot1_ax2ay2"
add_label(id, 500, 500, "My label")

The label was added to the data system defined by the second set of axes created (plot1_ax2ay2).

Bugs

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.