next up previous 264
Next: AST_CLONE - Clone (duplicate) an Object pointer
Up: AST Routine Descriptions
Previous: AST_CLEAR - Clear attribute values for an Object


AST_CLIP - Set up or remove clipping for a Plot

Description:
This routine defines regions of a Plot which are to be clipped. Any subsequent graphical output created using the Plot will then be visible only within the unclipped regions of the plotting area. See also the Clip attribute.
Invocation:
CALL AST_CLIP( THIS, IFRAME, LBND, UBND, STATUS )
Arguments:
THIS = INTEGER (Given)
Pointer to the Plot.
IFRAME = INTEGER (Given)
The index of the Frame within the Plot to which the clipping limits supplied in LBND and UBND (below) refer. Clipping may be applied to any of the coordinate systems associated with a Plot (as defined by the Frames it contains), so this index may take any value from 1 to the number of Frames in the Plot (Nframe attribute). In addition, the values AST__BASE and AST__CURRENT may be used to specify the base and current Frames respectively.

For example, a value of AST__CURRENT causes clipping to be performed in physical coordinates, while a value of AST__BASE would clip in graphical coordinates. Clipping may also be removed completely by giving a value of AST__NOFRAME. In this case any clipping bounds supplied (below) are ignored.

LBND( $*$ ) = DOUBLE PRECISION (Given)
An array with one element for each axis of the clipping Frame (identified by the index IFRAME). This should contain the lower bound, on each axis, of the region which is to remain visible (unclipped).
UBND( $*$ ) = DOUBLE PRECISION (Given)
An array with one element for each axis of the clipping Frame (identified by the index IFRAME). This should contain the upper bound, on each axis, of the region which is to remain visible (unclipped).
STATUS = INTEGER (Given and Returned)
The global status.
Notes:
  • Only one clipping Frame may be active at a time. This routine will deactivate any previously-established clipping Frame before setting up new clipping limits.

  • The clipping produced by this routine is in addition to that specified by the Clip attribute which occurs at the edges of the plotting area established when the Plot is created (see AST_PLOT). The underlying graphics system may also impose further clipping.

  • When testing a graphical position for clipping, it is first transformed into the clipping Frame. The resulting coordinate on each axis is then checked against the clipping limits (given by LBND and UBND). By default, a position is clipped if any coordinate lies outside these limits. However, if a non-zero value is assigned to the Plot's ClipOp attribute, then a position is only clipped if the coordinates on all axes lie outside their clipping limits.

  • If the lower clipping limit exceeds the upper limit for any axis, then the sense of clipping for that axis is reversed (so that coordinate values lying between the limits are clipped instead of those lying outside the limits). To produce a "hole" in a coordinate space (that is, an internal region where nothing is plotted), you should supply all the bounds in reversed order, and set the ClipOp attribute for the Plot to a non-zero value.

  • Either clipping limit may be set to the value AST__BAD, which is equivalent to setting it to infinity (or minus infinity for a lower bound) so that it is not used.

  • If a graphical position results in any bad coordinate values (AST__BAD) when transformed into the clipping Frame, then it is treated (for the purposes of producing graphical output) as if it were clipped.

  • When a Plot is used as a Mapping to transform points (e.g. using AST_TRAN2), any clipped output points are assigned coordinate values of AST__BAD.

  • An error results if the base Frame of the Plot is not 2-dimensional.


next up previous 264
Next: AST_CLONE - Clone (duplicate) an Object pointer
Up: AST Routine Descriptions
Previous: AST_CLEAR - Clear attribute values for an Object

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council