|AHELP for CIAO 4.9 ChIPS v1||
Creates a line connecting two or more points.
add_line([id,] x1, y1, x2, y2 [,attributes]) add_line([id,] xvals, yvals, [,attributes]) Polylines can also be created directly from the GUI using the "Annotate" menu item.
The function arguments.
|id||A ChipsId structure identifying the item.|
|x1, y1, x2, y2||The endpoints of the line segment, (x1,y1) and (x2,y2); the current coordinate system is used if the "coordsys" attribute is not set.|
|xvals, yvals||Arrays of x and y coordinates to create a polyline from (xvals,yvals) to (xpos[n], yvals[n]); the current coordinate system is used if the "coordsys" attribute is not set.|
|attributes||Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.|
The add_line command creates a line segment whose attributes are specified by user preferences or in an attribute list. The new line becomes current by default; providing a ChipsId overrides the currency state.
The endpoints of the line can be specified in data, pixel, frame, or plot normalized coordinates by using the 'coordsys' attribute. Lines specified in data coordinates will be clipped at plot boundaries. The "extend" attribute enables lines which extend to infinity.
Lines are not automatically closed, so if you require a closed curve then make sure that the last coordinate is the same as the first one. They are also not able to be filled. However, unlike regions, lines can intersect themselves. See add_region for details on how to create a region in ChIPS.
The add_hline() and add_vline() routines can be used to easily add a horizontal or vertical line respectively to a plot. These routines are short cuts to calling add_line() and setting the "extend" attribute to "both". See "ahelp add_hline" and "ahelp add_vline" for more information.
There are several attributes that control the line characteristics. The attributes can be set to the ChIPS defaults, values provided in the add_line command, or values from the user's preference file.
Please see the section "Line Preferences and Attributes" below the examples for a list of the line preferences.
Add a diagonal line extending from (.1,.1) to (.9,.9) in the current coordinate system.
chips> lopt = ChipsLine() chips> lopt.color = "blue" chips> lopt.thickness = 0.5 chips> lopt.stem = "MyLine" chips> add_line(100, 100, 200, 150, lopt)
Populate the "lopt" structure with the attribute values, then add a line segment from (100,100) to (200,150).
chips> add_line([.1,.5,.9],[.9,.2,.7], ["color", "blue", "style", "dot"])
Create a blue dotted line comprised of two segments, specifying the attribute values in a list.
chips> add_line(1, 0, 2, 0, ["extend", "both"]) chips> limits(X_AXIS, 100, 200)
Adds a line to the plot at y=0 which extends to both edges of the plot, no matter how the limits are changed. A simpler way to achieve this is to use the add_hline() routine:
chips> add_line(0.05, 0.9, 0.0, 0.05, ["coordsys", FRAME_NORM])
Adds a line to the frame using the frame-normalized coordinate system. In this case the line goes from close to the top-left corner to close to the bottom-right corner of the frame.
The attributes associated with lines are given in the following table, where the "Set?" column refers to whether the attribute can be change using the set_line() command. To change the line preference settings prepend "line." to the attribute name.
|color||line color||name or hex; see the Color section of "ahelp chipsopt"||default||Yes|
|coordsys||coordinate system for the line||PIXEL, WINDOW_NORM, FRAME_NORM, PLOT_NORM, DATA||see "ahelp coordsys"||No|
|depth||Integer value indicating line depth||see the Depth section of "ahelp chipsopt"||default||Yes|
|extend||Should the line extend to infinity (segment vs ray)||One of "none", "both", "start", "end", chips_extend_none, chips_extend_both, chips_extend_start, or chips_extend_end.||chips_extend_none||Yes|
|stem||stem used for line id||An alpha-numeric character sequence that does not contain a space||line||No|
|style||stipple pattern used to draw the line segment||see the Line Style section of "ahelp chipsopt"||chips_solid||Yes|
|thickness||line thickness||0.5 to 10.0; see the Thickness section of "ahelp chipsopt"||1||Yes|
See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.