Last modified: December 2013

URL: https://cxc.cfa.harvard.edu/chips/ahelp/Coordinates.html
Jump to: Description · Bugs · See Also


AHELP for CIAO 4.11 ChIPS v1

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.

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.

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.

See Also

chips
chips, chipsgui, chipsrc, show_gui
concepts
aspectratio, attributes, chipsid, chipsopt, colors, currency, depthcontrol, entitycreation, preferences, setget
coordinates
convert_coordinate