diff options
Diffstat (limited to 'ast/region.c')
| -rw-r--r-- | ast/region.c | 13502 |
1 files changed, 13502 insertions, 0 deletions
diff --git a/ast/region.c b/ast/region.c new file mode 100644 index 0000000..5148917 --- /dev/null +++ b/ast/region.c @@ -0,0 +1,13502 @@ +/* +*class++ +* Name: +* Region + +* Purpose: +* Represents a region within a coordinate system. + +* Constructor Function: +* None. + +* Description: +* This class provides the basic facilities for describing a region within +* a specified coordinate system. However, the Region class does not +* have a constructor function of its own, as it is simply a container +* class for a family of specialised sub-classes such as Circle, Box, etc, +* which implement Regions with particular shapes. +* +* All sub-classes of Region require a Frame to be supplied when the Region +* is created. This Frame describes the coordinate system in which the +* Region is defined, and is referred to as the "encapsulated Frame" below. +* Constructors will also typically required one or more positions to be +* supplied which define the location and extent of the region. These +* positions must be supplied within the encapsulated Frame. +* +* The Region class inherits from the Frame class, and so a Region can be +* supplied where-ever a Frame is expected. In these cases, supplying a +* Region is equivalent to supplying a reference to its encapsulated Frame. +* Thus all the methods of the Frame class can be used on the Region class. +* For instance, the +c astFormat function +f AST_FORMAT routine +* may be used on a Region to format an axis value. +* +* In addition, since Frame inherits from Mapping, a Region is also a sort +* of Mapping. Transforming positions by supplying a Region to one of the +c astTran<X> functions +f AST_TRAN<X> routines +* is the way to determine if a given position is inside or outside the +* Region. When used as a Mapping, most classes of Frame are equivalent to +* a UnitMap. However, the Region class modifies this behaviour so that a +* Region acts like a UnitMap only for input positions which are within the +* area represented by the Region. Input positions which are outside the +* area produce bad output values (i.e. the output values are equal to +* AST__BAD). This behaviour is the same for both the forward and the +* inverse transformation. In this sense the "inverse transformation" +* is not a true inverse of the forward transformation, since applying +* the forward transformation to a point outside the Region, and then +* applying the inverse transformation results, in a set of AST__BAD axis +* values rather than the original axis values. If required, the +c astRemoveRegions +f AST_REMOVEREGIONS +* function can be used to remove the "masking" effect of any Regions +* contained within a compound Mapping or FrameSet. It does this by +* replacing each Region with a UnitMap or equivalent Frame (depending +* on the context in which the Region is used). +* +* If the coordinate system represented by the Region is changed (by +* changing the values of one or more of the attribute which the Region +* inherits from its encapsulated Frame), the area represented by +* the Region is mapped into the new coordinate system. For instance, let's +* say a Circle (a subclass of Region) is created, a SkyFrame being +* supplied to the constructor so that the Circle describes a circular +* area on the sky in FK4 equatorial coordinates. Since Region inherits +* from Frame, the Circle will have a System attribute and this attribute +* will be set to "FK4". If the System attribute of the Region is then +* changed from FK4 to FK5, the circular area represented by the Region +* will automatically be mapped from the FK4 system into the FK5 system. +* In general, changing the coordinate system in this way may result in the +* region changing shape - for instance, a circle may change into an +* ellipse if the transformation from the old to the new coordinate system +* is linear but with different scales on each axis. Thus the specific +* class of a Region cannot be used as a guarantee of the shape in any +* particular coordinate system. If the +c astSimplify function +f AST_SIMPLIFY routine +* is used on a Region, it will endeavour to return a new Region of +* a sub-class which accurately describes the shape in the current +* coordinate system of the Region (but this may not always be possible). +* +* It is possible to negate an existing Region so that it represents all +* areas of the encapsulated Frame except for the area specified when +* the Region was created. + +* Inheritance: +* The Region class inherits from the Frame class. + +* Attributes: +* In addition to those attributes common to all Frames, every +* Region also has the following attributes: +* +* - Adaptive: Should the area adapt to changes in the coordinate system? +* - Negated: Has the original region been negated? +* - Closed: Should the boundary be considered to be inside the region? +* - MeshSize: Number of points used to create a mesh covering the Region +* - FillFactor: Fraction of the Region which is of interest +* - Bounded: Is the Region bounded? +* +* Every Region also inherits any further attributes that belong +* to the encapsulated Frame, regardless of that Frame's class. (For +* example, the Equinox attribute, defined by the SkyFrame class, is +* inherited by any Region which represents a SkyFrame.) + +* Functions: +c In addition to those functions applicable to all Frames, the +c following functions may also be applied to all Regions: +f In addition to those routines applicable to all Frames, the +f following routines may also be applied to all Regions: +* +c - astGetRegionBounds: Get the bounds of a Region +f - AST_GETREGIONBOUNDS: Get the bounds of a Region +c - astGetRegionFrame: Get a copy of the Frame represent by a Region +f - AST_GETREGIONFRAME: Get a copy of the Frame represent by a Region +c - astGetRegionFrameSet: Get a copy of the Frameset encapsulated by a Region +f - AST_GETREGIONFRAMESET: Get a copy of the Frameset encapsulated by a Region +c - astGetRegionMesh: Get a mesh of points covering a Region +f - AST_GETREGIONMESH: Get a mesh of points covering a Region +c - astGetRegionPoints: Get the positions that define a Region +f - AST_GETREGIONPOINTS: Get the positions that define a Region +c - astGetUnc: Obtain uncertainty information from a Region +f - AST_GETUNC: Obtain uncertainty information from a Region +c - astMapRegion: Transform a Region into a new coordinate system +f - AST_MAPREGION: Transform a Region into a new coordinate system +c - astNegate: Toggle the value of the Negated attribute +f - AST_NEGATE: Toggle the value of the Negated attribute +c - astOverlap: Determines the nature of the overlap between two Regions +f - AST_OVERLAP: Determines the nature of the overlap between two Regions +c - astMask<X>: Mask a region of a data grid +f - AST_MASK<X>: Mask a region of a data grid +c - astSetUnc: Associate a new uncertainty with a Region +f - AST_SETUNC: Associate a new uncertainty with a Region +c - astShowMesh: Display a mesh of points on the surface of a Region +f - AST_SHOWMESH: Display a mesh of points on the surface of a Region + +* Copyright: +* Copyright (C) 1997-2006 Council for the Central Laboratory of the +* Research Councils +* Copyright (C) 2009 Science & Technology Facilities Council. +* All Rights Reserved. + +* Licence: +* This program is free software: you can redistribute it and/or +* modify it under the terms of the GNU Lesser General Public +* License as published by the Free Software Foundation, either +* version 3 of the License, or (at your option) any later +* version. +* +* This program is distributed in the hope that it will be useful, +* but WITHOUT ANY WARRANTY; without even the implied warranty of +* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +* GNU Lesser General Public License for more details. +* +* You should have received a copy of the GNU Lesser General +* License along with this program. If not, see +* <http://www.gnu.org/licenses/>. + +* Authors: +* DSB: David S. Berry (STARLINK) + +* History: +* 3-DEC-2003 (DSB): +* Original version. +* 12-MAY-2005 (DSB): +* Override astNormBox method. +* 12-AUG-2005 (DSB): +* Override ObsLat and ObsLon accessor methods. +* 14-FEB-2006 (DSB): +* Override astGetObjSize. +* 2-MAR-2006 (DSB): +* Changed AST_LONG_DOUBLE to HAVE_LONG_DOUBLE. +* 14-MAR-2006 (DSB): +* Added astGetRefFS. +* 28-MAY-2007 (DSB): +* - Added protected function astBndMesh. +* 14-JAN-2009 (DSB): +* Override the astIntersect method. +* 20-JAN-2009 (DSB): +* Change astPickAxes so that it returns a Region rather than a +* Frame if possible. This included adding method astRegBasePick. +* 9-FEB-2009 (DSB): +* Move PointList methods astGetEnclosure and astSetEnclosure to +* Region. +* 18-FEB-2009 (DSB): +* Remove methods astGetEnclosure and astSetEnclosure. +* 15-JUN-2009 (DSB): +* Modify MapRegion to use FrameSets properly. +* 18-JUN-2009 (DSB): +* Override ObsAlt accessor methods. +* 7-SEP-2009 (DSB): +* Fix astMask to avoid reading variance values from the data array. +* 8-SEP-2009 (DSB): +* Fix bugs in astOverlap that could result in wrong results if +* either region is unbounded. +* 4-JAN-2010 (DSB): +* Fix bug in GetRegionBounds (it was assumed implicitly that the base +* Frame had the same number of axes as the current Frame). +* 18-MAR-2011 (DSB): +* Added astGetRegionMesh public method. +* 22-MAR-2011 (DSB): +* Improve uniformity of points produced by astRegBaseGrid method. +* 29-APR-2011 (DSB): +* Prevent astFindFrame from matching a subclass template against a +* superclass target. +* 17-MAY-2011 (DSB): +* In RegBaseGrid, accept the final try even if it is not within 5% +* of the required meshsize. +* 27-APR-2012 (DSB): +* Store a negated copy of itself with each Region. Changing the Negated +* attribute of a Region causes the cached information to be reset, and +* re-calculating it can be an expensive operation. So instead of changing +* "Negatated" in "this", access the negated copy of "this" using the +* new protected method astGetNegation. +* 7-JUN-2012 (DSB): +* Added protected astRegSplit method to split a Region into disjoint +* component regions. +* 15-JUN-2012 (DSB): +* Guard against division by zero in RegBase Grid if "ipr" is zero. +* 7-NOV-2013 (DSB): +* Added method astGetRegionFrameSet. +* 3-FEB-2014 (DSB): +* Fix bug masking regions that have no overlap with the supplied array. +* 17-APR-2015 (DSB): +* Added Centre. +* 26-OCT-2016 (DSB): +* - Override the astAxNorm method. +* - Use astAxNorm to fix a bug in astGetRegionBounds for cases where +* the Region cross a longitude=0 singularity. +* 11-NOV-2016 (DSB): +* When loading a Region, use the dimensionality of the base Frame +* of the FrameSet (rather than the current Frame as it used to be) +* to define the number of axes required in the PointSet. +* 1-DEC-2016 (DSB): +* Changed MapRegion to remove any unnecessary base frame axes in +* the returned Region. +*class-- + +* Implementation Notes: +* - All sub-classes must over-ride the following abstract methods declared +* in this class: astRegBaseBox, astRegBaseMesh, astRegPins, astRegCentre. +* They must also extend the astTransform method. In addition they should +* usually extend astSimplify. + +*/ + +/* Module Macros. */ +/* ============== */ +/* Set the name of the class we are implementing. This indicates to + the header files that define class interfaces that they should make + "protected" symbols available. */ +#define astCLASS Region + +/* Value for Ident attribute of of an encapsulated FrameSet which + indicates that it is a dummy FrameSet (see astRegDummy). */ +#define DUMMY_FS "ASTREGION-DUMMY" + +/* +* Name: +* MAKE_CLEAR + +* Purpose: +* Define a function to clear an attribute value for a Region. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_CLEAR(attribute) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static void Clear<Attribute>( AstFrame *this ) +* +* that clears the value of a specified attribute for the encapsulated +* FrameSet within a Region (this). This function is intended to over-ride +* the astClear<Attribute> method inherited from the Frame class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +*/ + +/* Define the macro. */ +#define MAKE_CLEAR(attribute) \ +static void Clear##attribute( AstFrame *this_frame, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to the Region structure */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Obtain a pointer to the encapsulated FrameSet and invoke its \ + astClear method. The protected astClear##attribute method is not used \ + because we want the current Frame of the FrameSet tp be re-mapped if \ + necessary. */ \ + astClear( this->frameset, #attribute ); \ +} + +/* +* Name: +* MAKE_CLEAR_AXIS + +* Purpose: +* Define a function to clear an attribute value for a Region axis. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_CLEAR_AXIS(attribute) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static void Clear<Attribute>( AstFrame *this, int axis ) +* +* that clears the value of a specified attribute for an axis of +* the encapsulated FrameSet within a Region (this). This function is +* intended to over-ride the astClear<Attribute> method inherited +* from the Frame class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +*/ + +/* Define the macro. */ +#define MAKE_CLEAR_AXIS(attribute) \ +static void Clear##attribute( AstFrame *this_frame, int axis, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to the Region structure */ \ + char buf[100]; /* Buffer for attribute name */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Validate the axis index supplied. */ \ + (void) astValidateAxis( this, axis, 1, "astClear" #attribute ); \ +\ +/* We use the public astSetx method rather than the protected \ + astSet#attribute method so that the current Frame in the encapsulated \ + FrameSet will be re-mapped if necessary. Construct the attribute name. */ \ + sprintf( buf, "%s(%d)", #attribute, axis + 1 ); \ +\ +/* Obtain a pointer to the Region's encapsulated FrameSet and invoke its \ + astClear method. The protected astClear#attribute method is notused \ + since we want the current Frame of the encapsulated FrameSet to be \ + remapped if required. */ \ + astClear( this->frameset, buf ); \ +} + +/* +* Name: +* MAKE_GET + +* Purpose: +* Define a function to get an attribute value for a Region. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_GET(attribute,type) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static <type> Get<Attribute>( AstFrame *this ) +* +* that gets the value of a specified attribute for the encapsulated +* FrameSet of a Region (this). This function is intended to over-ride +* the astGet<Attribute> method inherited from the Frame class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +* type +* The C type of the attribute. +*/ + +/* Define the macro. */ +#define MAKE_GET(attribute,type) \ +static type Get##attribute( AstFrame *this_frame, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to the Region structure */ \ + type result; /* Value to return */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return (type) 0; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Obtain a pointer to the encapsulated FrameSet and invoke its \ + astGet<Attribute> method. */ \ + result = astGet##attribute( this->frameset ); \ +\ +/* If an error occurred, clear the result value. */ \ + if ( !astOK ) result = (type) 0; \ +\ +/* Return the result. */ \ + return result; \ +} + +/* +* Name: +* MAKE_GET_AXIS + +* Purpose: +* Define a function to get an attribute value for a Region axis. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_GET_AXIS(attribute,type) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static <type> Get<Attribute>( AstFrame *this, int axis ) +* +* that gets the value of a specified attribute for an axis of the +* encapsulated FrameSet within a Region (this). This function is intended +* to over-ride the astGet<Attribute> method inherited from the Frame +* class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +* type +* The C type of the attribute. +*/ + +/* Define the macro. */ +#define MAKE_GET_AXIS(attribute,type) \ +static type Get##attribute( AstFrame *this_frame, int axis, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to the Region structure */ \ + type result; /* Value to return */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return (type) 0; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Validate the axis index supplied. */ \ + (void) astValidateAxis( this, axis, 1, "astGet" #attribute ); \ +\ +/* Obtain a pointer to the Region's encapsulated FrameSet and invoke its \ + astGet<Attribute> method. */ \ + result = astGet##attribute( this->frameset, axis ); \ +\ +/* If an error occurred, clear the result value. */ \ + if ( !astOK ) result = (type) 0; \ +\ +/* Return the result. */ \ + return result; \ +} + +/* +* Name: +* MAKE_SET_SYSTEM + +* Purpose: +* Define a function to set a System attribute value for a Region. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_SET_SYSTEM(attribute) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static void Set<Attribute>( AstFrame *this, AstSystemType value ) +* +* that sets the value of a specified attribute for the encapsulated +* FrameSet of a Region (this). This function is intended to over-ride the +* astSet<Attribute> method inherited from the Frame class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +*/ + +/* Define the macro. */ +#define MAKE_SET_SYSTEM(attribute) \ +static void Set##attribute( AstFrame *this_frame, AstSystemType value, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to the Region structure */ \ + const char *text; /* Pointer to system string */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Convert the supplied value to a string using the astSystemString + method of the current Frame in the encapsulated FrameSet. */ \ + text = astSystemString( this->frameset, value ); \ +\ +/* Set the value by invoking the public astSetC method on the encapusulated \ + FrameSet. This ensures that the current Frame of the encapsulated \ + FrameSet is re-mapped if necessary. */ \ + astSetC( this->frameset, #attribute, text ); \ +} + +/* +* Name: +* MAKE_SET + +* Purpose: +* Define a function to set an attribute value for a Region. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_SET(attribute,type,x) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static void Set<Attribute>( AstFrame *this, <type> value ) +* +* that sets the value of a specified attribute for the encapsulated +* FrameSet of a Region (this). This function is intended to over-ride the +* astSet<Attribute> method inherited from the Frame class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +* type +* The C type of the attribute. +* x +* The single character code for the astSetx function for the given C +* type. +*/ + +/* Define the macro. */ +#define MAKE_SET(attribute,type,x) \ +static void Set##attribute( AstFrame *this_frame, type value, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to the Region structure */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Set the value by invoking the public astSetx method on the encapusulated \ + FrameSet. This ensures that the current Frame of the encapsulated \ + FrameSet is re-mapped if necessary. */ \ + astSet##x( this->frameset, #attribute, value ); \ +} + +/* +* Name: +* MAKE_SET_AXIS + +* Purpose: +* Define a function to set an attribute value for a Region axis. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_SET_AXIS(attribute,type,x) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static void Set<Attribute>( AstFrame *this, int axis, <type> value ) +* +* that sets the value of a specified attribute for an axis of the +* encapsulated FrameSet within a Region (this). This function is intended +* to over-ride the astSet<Attribute> method inherited from the Frame +* class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +* type +* The C type of the attribute. +* x +* The single character code for the astSetx function for the given C +* type. +*/ + +/* Define the macro. */ +#define MAKE_SET_AXIS(attribute,type,x) \ +static void Set##attribute( AstFrame *this_frame, int axis, type value, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to the Region structure */ \ + char buf[100]; /* Buffer for attribute name */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Validate the axis index supplied. */ \ + (void) astValidateAxis( this, axis, 1, "astSet" #attribute ); \ +\ +/* We use the public astSetx method rather than the protected \ + astSet#attribute method so that the current Frame in the encapsulated \ + FrameSet will be re-mapped if necessary. Construct the attribute name. */ \ + sprintf( buf, "%s(%d)", #attribute, axis + 1 ); \ +\ +/* Obtain a pointer to the Region's encapsulated FrameSet and invoke its \ + astSet<x> method. */ \ + astSet##x( this->frameset, buf, value ); \ +} + +/* +* Name: +* MAKE_TEST + +* Purpose: +* Define a function to test if an attribute value is set for a Region. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_TEST(attribute) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static int Test<Attribute>( AstFrame *this ) +* +* that returns a boolean result (0 or 1) to indicate if the value +* of a specified attribute for the encapsulated FrameSet within a +* Region (this) is set. This function is intended to over-ride the +* astTest<Attribute> method inherited from the Frame class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +*/ + +/* Define the macro. */ +#define MAKE_TEST(attribute) \ +static int Test##attribute( AstFrame *this_frame, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to Region structure */ \ + int result; /* Result to return */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return 0; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Obtain a pointer to the Region's encapsulated FrameSet and invoke its \ + astTest<Attribute> method. */ \ + result = astTest##attribute( this->frameset ); \ +\ +/* If an error occurred, clear the result value. */ \ + if ( !astOK ) result = 0; \ +\ +/* Return the result. */ \ + return result; \ +} + +/* +* Name: +* MAKE_TEST_AXIS + +* Purpose: +* Define a function to test if an attribute value is set for a Region +* axis. + +* Type: +* Private macro. + +* Synopsis: +* #include "region.h" +* MAKE_TEST_AXIS(attribute) + +* Class Membership: +* Defined by the Region class. + +* Description: +* This macro expands to an implementation of a private member function +* of the form: +* +* static int Test<Attribute>( AstFrame *this, int axis ) +* +* that returns a boolean result (0 or 1) to indicate if the value +* of a specified attribute for an axis of the encapsulated FrameSet +* within a Region (this) is set. This function is intended to over-ride +* the astTest<Attribute> method inherited from the Frame class. + +* Parameters: +* attribute +* Name of the attribute, as it appears in the function name. +*/ + +/* Define the macro. */ +#define MAKE_TEST_AXIS(attribute) \ +static int Test##attribute( AstFrame *this_frame, int axis, int *status ) { \ +\ +/* Local Variables: */ \ + AstRegion *this; /* Pointer to the Region structure */ \ + int result; /* Value to return */ \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return 0; \ +\ +/* Obtain a pointer to the Region structure. */ \ + this = (AstRegion *) this_frame; \ +\ +/* Validate the axis index supplied. */ \ + (void) astValidateAxis( this, axis, 1, "astTest" #attribute ); \ +\ +/* Obtain a pointer to the Region's encapsulated FrameSet and invoke its \ + astTest<Attribute> method. */ \ + result = astTest##attribute( this->frameset, axis ); \ +\ +/* If an error occurred, clear the result value. */ \ + if ( !astOK ) result = 0; \ +\ +/* Return the result. */ \ + return result; \ +} + +/* Header files. */ +/* ============= */ +/* Interface definitions. */ +/* ---------------------- */ + +#include "globals.h" /* Thread-safe global data access */ +#include "error.h" /* Error reporting facilities */ +#include "memory.h" /* Memory allocation facilities */ +#include "object.h" /* Base Object class */ +#include "mapping.h" /* Coordinate Mappings */ +#include "unitmap.h" /* Unit Mappings */ +#include "permmap.h" /* Coordinate permutation Mappings */ +#include "cmpmap.h" /* Compound Mappings */ +#include "frame.h" /* Parent Frame class */ +#include "frameset.h" /* Interconnected coordinate systems */ +#include "region.h" /* Interface definition for this class */ +#include "circle.h" /* Circular regions */ +#include "box.h" /* Box regions */ +#include "cmpregion.h" /* Compound regions */ +#include "ellipse.h" /* Elliptical regions */ +#include "pointset.h" /* Sets of points */ +#include "globals.h" /* Thread-safe global data access */ + +/* Error code definitions. */ +/* ----------------------- */ +#include "ast_err.h" /* AST error codes */ + +/* C header files. */ +/* --------------- */ +#include <ctype.h> +#include <limits.h> +#include <stdarg.h> +#include <stddef.h> +#include <stdio.h> +#include <string.h> +#include <stdlib.h> +#include <math.h> + +/* Module Variables. */ +/* ================= */ + +/* Address of this static variable is used as a unique identifier for + member of this class. */ +static int class_check; + +/* Pointers to parent class methods which are extended by this class. */ +static int (* parent_getobjsize)( AstObject *, int * ); +static int (* parent_getusedefs)( AstObject *, int * ); + +#if defined(THREAD_SAFE) +static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); +#endif + +/* Define macros for accessing each item of thread specific global data. */ +#ifdef THREAD_SAFE + +/* Define how to initialise thread-specific globals. */ +#define GLOBAL_inits \ + globals->Class_Init = 0; \ + globals->GetAttrib_Buff[ 0 ] = 0; + +/* Create the function that initialises global data for this module. */ +astMAKE_INITGLOBALS(Region) + +/* Define macros for accessing each item of thread specific global data. */ +#define class_init astGLOBAL(Region,Class_Init) +#define class_vtab astGLOBAL(Region,Class_Vtab) +#define getattrib_buff astGLOBAL(Region,GetAttrib_Buff) + + + +/* If thread safety is not needed, declare and initialise globals at static + variables. */ +#else + +static char getattrib_buff[ 101 ]; + + +/* Define the class virtual function table and its initialisation flag + as static variables. */ +static AstRegionVtab class_vtab; /* Virtual function table */ +static int class_init = 0; /* Virtual function table initialised? */ + +#endif + +/* Prototypes for Private Member Functions. */ +/* ======================================== */ +#if HAVE_LONG_DOUBLE /* Not normally implemented */ +static int MaskLD( AstRegion *, AstMapping *, int, int, const int[], const int ubnd[], long double [], long double, int * ); +#endif +static int MaskB( AstRegion *, AstMapping *, int, int, const int[], const int[], signed char[], signed char, int * ); +static int MaskD( AstRegion *, AstMapping *, int, int, const int[], const int[], double[], double, int * ); +static int MaskF( AstRegion *, AstMapping *, int, int, const int[], const int[], float[], float, int * ); +static int MaskI( AstRegion *, AstMapping *, int, int, const int[], const int[], int[], int, int * ); +static int MaskL( AstRegion *, AstMapping *, int, int, const int[], const int[], long int[], long int, int * ); +static int MaskS( AstRegion *, AstMapping *, int, int, const int[], const int[], short int[], short int, int * ); +static int MaskUB( AstRegion *, AstMapping *, int, int, const int[], const int[], unsigned char[], unsigned char, int * ); +static int MaskUI( AstRegion *, AstMapping *, int, int, const int[], const int[], unsigned int[], unsigned int, int * ); +static int MaskUL( AstRegion *, AstMapping *, int, int, const int[], const int[], unsigned long int[], unsigned long int, int * ); +static int MaskUS( AstRegion *, AstMapping *, int, int, const int[], const int[], unsigned short int[], unsigned short int, int * ); + +static AstAxis *GetAxis( AstFrame *, int, int * ); +static AstFrame *GetRegionFrame( AstRegion *, int * ); +static AstFrameSet *GetRegionFrameSet( AstRegion *, int * ); +static AstFrame *PickAxes( AstFrame *, int, const int[], AstMapping **, int * ); +static AstFrame *RegFrame( AstRegion *, int * ); +static AstFrameSet *Conv( AstFrameSet *, AstFrameSet *, int * ); +static AstFrameSet *Convert( AstFrame *, AstFrame *, const char *, int * ); +static AstFrameSet *ConvertX( AstFrame *, AstFrame *, const char *, int * ); +static AstFrameSet *FindFrame( AstFrame *, AstFrame *, const char *, int * ); +static AstFrameSet *GetRegFS( AstRegion *, int * ); +static AstLineDef *LineDef( AstFrame *, const double[2], const double[2], int * ); +static AstMapping *RegMapping( AstRegion *, int * ); +static AstMapping *RemoveRegions( AstMapping *, int * ); +static AstMapping *Simplify( AstMapping *, int * ); +static AstObject *Cast( AstObject *, AstObject *, int * ); +static AstPointSet *BTransform( AstRegion *, AstPointSet *, int, AstPointSet *, int * ); +static AstPointSet *BndBaseMesh( AstRegion *, double *, double *, int * ); +static AstPointSet *BndMesh( AstRegion *, double *, double *, int * ); +static AstPointSet *GetSubMesh( int *, AstPointSet *, int * ); +static AstPointSet *RegBaseGrid( AstRegion *, int * ); +static AstPointSet *RegBaseMesh( AstRegion *, int * ); +static AstPointSet *RegGrid( AstRegion *, int * ); +static AstPointSet *RegMesh( AstRegion *, int * ); +static AstPointSet *RegTransform( AstRegion *, AstPointSet *, int, AstPointSet *, AstFrame **, int * ); +static AstPointSet *ResolvePoints( AstFrame *, const double [], const double [], AstPointSet *, AstPointSet *, int * ); +static AstRegion *MapRegion( AstRegion *, AstMapping *, AstFrame *, int * ); +static AstRegion *RegBasePick( AstRegion *, int, const int *, int * ); +static AstRegion **RegSplit( AstRegion *, int *, int * ); +static AstSystemType SystemCode( AstFrame *, const char *, int * ); +static AstSystemType ValidateSystem( AstFrame *, AstSystemType, const char *, int * ); +static const char *Abbrev( AstFrame *, int, const char *, const char *, const char *, int * ); +static const char *Format( AstFrame *, int, double, int * ); +static const char *SystemString( AstFrame *, AstSystemType, int * ); +static const int *GetPerm( AstFrame *, int * ); +static double *RegCentre( AstRegion *, double *, double **, int, int, int * ); +static double Angle( AstFrame *, const double[], const double[], const double[], int * ); +static double AxAngle( AstFrame *, const double[], const double[], int, int * ); +static double AxDistance( AstFrame *, int, double, double, int * ); +static double AxOffset( AstFrame *, int, double, double, int * ); +static double Distance( AstFrame *, const double[], const double[], int * ); +static double Centre( AstFrame *, int, double, double, int * ); +static double Gap( AstFrame *, int, double, int *, int * ); +static double Offset2( AstFrame *, const double[2], double, double, double[2], int * ); +static int Equal( AstObject *, AstObject *, int * ); +static int GetNaxes( AstFrame *, int * ); +static int GetObjSize( AstObject *, int * ); +static int GetUseDefs( AstObject *, int * ); +static int IsUnitFrame( AstFrame *, int * ); +static int LineContains( AstFrame *, AstLineDef *, int, double *, int * ); +static int LineCrossing( AstFrame *, AstLineDef *, AstLineDef *, double **, int * ); +static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); +static int Overlap( AstRegion *, AstRegion *, int * ); +static int OverlapX( AstRegion *, AstRegion *, int * ); +static int RegDummyFS( AstRegion *, int * ); +static int RegPins( AstRegion *, AstPointSet *, AstRegion *, int **, int * ); +static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); +static int RegTrace( AstRegion *, int, double *, double **, int * ); +static int Unformat( AstFrame *, int, const char *, double *, int * ); +static int ValidateAxis( AstFrame *, int, int, const char *, int * ); +static void AxNorm( AstFrame *, int, int, int, double *, int * ); +static void CheckPerm( AstFrame *, const int *, const char *, int * ); +static void Copy( const AstObject *, AstObject *, int * ); +static void Delete( AstObject *, int * ); +static void Dump( AstObject *, AstChannel *, int * ); +static void GetRegionBounds( AstRegion *, double *, double *, int * ); +static void GetRegionBounds2( AstRegion *, double *, double *, int * ); +static void GetRegionMesh( AstRegion *, int, int, int, int *, double *, int * ); +static void GetRegionPoints( AstRegion *, int, int, int *, double *, int * ); +static void Intersect( AstFrame *, const double[2], const double[2], const double[2], const double[2], double[2], int * ); +static void LineOffset( AstFrame *, AstLineDef *, double, double, double[2], int * ); +static void MatchAxes( AstFrame *, AstFrame *, int *, int * ); +static void MatchAxesX( AstFrame *, AstFrame *, int *, int * ); +static void Negate( AstRegion *, int * ); +static void Norm( AstFrame *, double[], int * ); +static void NormBox( AstFrame *, double[], double[], AstMapping *, int * ); +static void Offset( AstFrame *, const double[], const double[], double, double[], int * ); +static void Overlay( AstFrame *, const int *, AstFrame *, int * ); +static void PermAxes( AstFrame *, const int[], int * ); +static void RegBaseBox( AstRegion *, double *, double *, int * ); +static void RegBaseBox2( AstRegion *, double *, double *, int * ); +static void RegClearAttrib( AstRegion *, const char *, char **, int * ); +static void RegOverlay( AstRegion *, AstRegion *, int, int * ); +static void RegSetAttrib( AstRegion *, const char *, char **, int * ); +static void ReportPoints( AstMapping *, int, AstPointSet *, AstPointSet *, int * ); +static void ResetCache( AstRegion *, int * ); +static void Resolve( AstFrame *, const double [], const double [], const double [], double [], double *, double *, int * ); +static void SetAxis( AstFrame *, int, AstAxis *, int * ); +static void SetRegFS( AstRegion *, AstFrame *, int * ); +static void ShowMesh( AstRegion *, int, const char *, int * ); +static void ValidateAxisSelection( AstFrame *, int, const int *, const char *, int * ); +static AstRegion *GetNegation( AstRegion *, int * ); + +static int GetBounded( AstRegion *, int * ); +static AstRegion *GetDefUnc( AstRegion *, int * ); + +static AstRegion *GetUncFrm( AstRegion *, int, int * ); +static AstRegion *GetUnc( AstRegion *, int, int * ); +static int TestUnc( AstRegion *, int * ); +static void ClearUnc( AstRegion *, int * ); +static void SetUnc( AstRegion *, AstRegion *, int * ); + +static const char *GetDomain( AstFrame *, int * ); +static int TestDomain( AstFrame *, int * ); +static void ClearDomain( AstFrame *, int * ); +static void SetDomain( AstFrame *, const char *, int * ); + +static const char *GetFormat( AstFrame *, int, int * ); +static int TestFormat( AstFrame *, int, int * ); +static void ClearFormat( AstFrame *, int, int * ); +static void SetFormat( AstFrame *, int, const char *, int * ); + +static const char *GetLabel( AstFrame *, int, int * ); +static int TestLabel( AstFrame *, int, int * ); +static void ClearLabel( AstFrame *, int, int * ); +static void SetLabel( AstFrame *, int, const char *, int * ); + +static const char *GetSymbol( AstFrame *, int, int * ); +static int TestSymbol( AstFrame *, int, int * ); +static void ClearSymbol( AstFrame *, int, int * ); +static void SetSymbol( AstFrame *, int, const char *, int * ); + +static const char *GetTitle( AstFrame *, int * ); +static void SetTitle( AstFrame *, const char *, int * ); +static void ClearTitle( AstFrame *, int * ); +static int TestTitle( AstFrame *, int * ); + +static const char *GetUnit( AstFrame *, int, int * ); +static int TestUnit( AstFrame *, int, int * ); +static void ClearUnit( AstFrame *, int, int * ); +static void SetUnit( AstFrame *, int, const char *, int * ); + +static int GetDigits( AstFrame *, int * ); +static int TestDigits( AstFrame *, int * ); +static void ClearDigits( AstFrame *, int * ); +static void SetDigits( AstFrame *, int, int * ); + +static int GetDirection( AstFrame *, int, int * ); +static int TestDirection( AstFrame *, int, int * ); +static void ClearDirection( AstFrame *, int, int * ); +static void SetDirection( AstFrame *, int, int, int * ); + +static int GetActiveUnit( AstFrame *, int * ); +static int TestActiveUnit( AstFrame *, int * ); +static void SetActiveUnit( AstFrame *, int, int * ); + +static int GetMatchEnd( AstFrame *, int * ); +static int TestMatchEnd( AstFrame *, int * ); +static void ClearMatchEnd( AstFrame *, int * ); +static void SetMatchEnd( AstFrame *, int, int * ); + +static int GetMaxAxes( AstFrame *, int * ); +static int TestMaxAxes( AstFrame *, int * ); +static void ClearMaxAxes( AstFrame *, int * ); +static void SetMaxAxes( AstFrame *, int, int * ); + +static int GetMinAxes( AstFrame *, int * ); +static int TestMinAxes( AstFrame *, int * ); +static void ClearMinAxes( AstFrame *, int * ); +static void SetMinAxes( AstFrame *, int, int * ); + +static int GetPermute( AstFrame *, int * ); +static int TestPermute( AstFrame *, int * ); +static void ClearPermute( AstFrame *, int * ); +static void SetPermute( AstFrame *, int, int * ); + +static int GetPreserveAxes( AstFrame *, int * ); +static int TestPreserveAxes( AstFrame *, int * ); +static void ClearPreserveAxes( AstFrame *, int * ); +static void SetPreserveAxes( AstFrame *, int, int * ); + +static double GetBottom( AstFrame *, int, int * ); +static int TestBottom( AstFrame *, int, int * ); +static void ClearBottom( AstFrame *, int, int * ); +static void SetBottom( AstFrame *, int, double, int * ); + +static double GetTop( AstFrame *, int, int * ); +static int TestTop( AstFrame *, int, int * ); +static void ClearTop( AstFrame *, int, int * ); +static void SetTop( AstFrame *, int, double, int * ); + +static double GetEpoch( AstFrame *, int * ); +static int TestEpoch( AstFrame *, int * ); +static void ClearEpoch( AstFrame *, int * ); +static void SetEpoch( AstFrame *, double, int * ); + +static double GetObsAlt( AstFrame *, int * ); +static int TestObsAlt( AstFrame *, int * ); +static void ClearObsAlt( AstFrame *, int * ); +static void SetObsAlt( AstFrame *, double, int * ); + +static double GetObsLat( AstFrame *, int * ); +static int TestObsLat( AstFrame *, int * ); +static void ClearObsLat( AstFrame *, int * ); +static void SetObsLat( AstFrame *, double, int * ); + +static double GetObsLon( AstFrame *, int * ); +static int TestObsLon( AstFrame *, int * ); +static void ClearObsLon( AstFrame *, int * ); +static void SetObsLon( AstFrame *, double, int * ); + +static AstSystemType GetSystem( AstFrame *, int * ); +static int TestSystem( AstFrame *, int * ); +static void ClearSystem( AstFrame *, int * ); +static void SetSystem( AstFrame *, AstSystemType, int * ); + +static AstSystemType GetAlignSystem( AstFrame *, int * ); +static int TestAlignSystem( AstFrame *, int * ); +static void ClearAlignSystem( AstFrame *, int * ); +static void SetAlignSystem( AstFrame *, AstSystemType, int * ); + +static const char *GetAttrib( AstObject *, const char *, int * ); +static int TestAttrib( AstObject *, const char *, int * ); +static void ClearAttrib( AstObject *, const char *, int * ); +static void SetAttrib( AstObject *, const char *, int * ); + +static int GetNegated( AstRegion *, int * ); +static int TestNegated( AstRegion *, int * ); +static void ClearNegated( AstRegion *, int * ); +static void SetNegated( AstRegion *, int, int * ); + +static int GetClosed( AstRegion *, int * ); +static int TestClosed( AstRegion *, int * ); +static void ClearClosed( AstRegion *, int * ); +static void SetClosed( AstRegion *, int, int * ); + +static int GetMeshSize( AstRegion *, int * ); +static int TestMeshSize( AstRegion *, int * ); +static void ClearMeshSize( AstRegion *, int * ); +static void SetMeshSize( AstRegion *, int, int * ); + +static double GetFillFactor( AstRegion *, int * ); +static int TestFillFactor( AstRegion *, int * ); +static void ClearFillFactor( AstRegion *, int * ); +static void SetFillFactor( AstRegion *, double, int * ); + +static int GetRegionFS( AstRegion *, int * ); +static int TestRegionFS( AstRegion *, int * ); +static void ClearRegionFS( AstRegion *, int * ); +static void SetRegionFS( AstRegion *, int, int * ); + +static int GetAdaptive( AstRegion *, int * ); +static int TestAdaptive( AstRegion *, int * ); +static void ClearAdaptive( AstRegion *, int * ); +static void SetAdaptive( AstRegion *, int, int * ); + +#if defined(THREAD_SAFE) +static int ManageLock( AstObject *, int, int, AstObject **, int * ); +#endif + + +/* Member functions. */ +/* ================= */ + +static const char *Abbrev( AstFrame *this_frame, int axis, const char *fmt, + const char *str1, const char *str2, int *status ) { +/* +* Name: +* Abbrev + +* Purpose: +* Abbreviate a formatted Region axis value by skipping leading fields. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* const char *Abbrev( AstFrame *this, int axis, const char *fmt, +* const char *str1, const char *str2, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astAbbrev +* method inherited from the Frame class). + +* Description: +* This function compares two Region axis values that have been +* formatted (using astFormat) and determines if they have any +* redundant leading fields (i.e. leading fields in common which +* can be suppressed when tabulating the values or plotting them on +* the axis of a graph). + +* Parameters: +* this +* Pointer to the Region +* axis +* The number of the Region axis for which the values have +* been formatted (axis numbering starts at zero for the first +* axis). +* fmt +* Pointer to a constant null-terminated string containing the +* format specification used to format the two values. +* str1 +* Pointer to a constant null-terminated string containing the +* first formatted value. +* str1 +* Pointer to a constant null-terminated string containing the +* second formatted value. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A pointer into the "str2" string which locates the first +* character in the first field that differs between the two +* formatted values. +* +* If the two values have no leading fields in common, the returned +* value will point at the start of string "str2". If the two +* values are equal, it will point at the terminating null at the +* end of this string. + +* Notes: +* - This function assumes that the format specification used was +* the same when both values were formatted and that they both +* apply to the same Region axis. +* - A pointer to the start of "str2" will be returned if this +* function is invoked with the global error status set, or if it +* should fail for any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + const char *result; /* Pointer value to return */ + +/* Check the global error status. */ + if ( !astOK ) return str2; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis, 1, "astAbbrev" ); + +/* Obtain a pointer to the Region's current Frame and invoke this + Frame's astAbbrev method to perform the processing. Annul the Frame + pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astAbbrev( fr, axis, fmt, str1, str2 ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result. */ + if ( !astOK ) result = str2; + +/* Return the result. */ + return result; +} + +static double Angle( AstFrame *this_frame, const double a[], + const double b[], const double c[], int *status ) { +/* +* Name: +* Angle + +* Purpose: +* Calculate the angle subtended by two points at a third point. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* double Angle( AstFrame *this, const double a[], const double b[], +* const double c[], int *status ) + +* Class Membership: +* Region member function (over-rides the protected astAngle +* method inherited from the Frame class). + +* Description: +* This function finds the angle at point B between the line joining points +* A and B, and the line joining points C and B. These lines will in fact be +* geodesic curves appropriate to the Frame in use. For instance, in +* SkyFrame, they will be great circles. + +* Parameters: +* this +* Pointer to the Frame. +* a +* An array of double, with one element for each Frame axis +* (Naxes attribute) containing the coordinates of the first point. +* b +* An array of double, with one element for each Frame axis +* (Naxes attribute) containing the coordinates of the second point. +* c +* An array of double, with one element for each Frame axis +* (Naxes attribute) containing the coordinates of the third point. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* astAngle +* The angle in radians, from the line AB to the line CB. If the +* Frame is 2-dimensional, it will be in the range $\pm \pi$, +* and positive rotation is in the same sense as rotation from +* the positive direction of axis 2 to the positive direction of +* axis 1. If the Frame has more than 2 axes, a positive value will +* always be returned in the range zero to $\pi$. + +* Notes: +* - A value of AST__BAD will also be returned if points A and B are +* co-incident, or if points B and C are co-incident. +* - A value of AST__BAD will also be returned if this function is +* invoked with the AST error status set, or if it should fail for +* any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double result; /* Value to return */ + +/* Check the global error status. */ + if ( !astOK ) return AST__BAD; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke this + Frame's astAngle method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astAngle( fr, a, b, c ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result. */ + if ( !astOK ) result = AST__BAD; + +/* Return the result. */ + return result; +} + +static double AxAngle( AstFrame *this_frame, const double a[], const double b[], int axis, int *status ) { +/* +* Name: +* AxAngle + +* Purpose: +* Returns the angle from an axis, to a line through two points. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* double AxAngle( AstFrame *this, const double a[], const double b[], int axis, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astAxAngle +* method inherited from the Frame class). + +* Description: +* This function finds the angle, as seen from point A, between the positive +* direction of a specified axis, and the geodesic curve joining point +* A to point B. + +* Parameters: +* this +* Pointer to the Frame. +* a +* An array of double, with one element for each Frame axis +* (Naxes attribute) containing the coordinates of the first point. +* b +* An array of double, with one element for each Frame axis +* (Naxes attribute) containing the coordinates of the second point. +* axis +* The number of the Frame axis from which the angle is to be +* measured (one-based) +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The angle in radians, from the positive direction of the +* specified axis, to the line AB. If the Frame is 2-dimensional, +* it will be in the range $\pm \pi$, and positive rotation is in +* the same sense as rotation from the positive direction of axis 2 +* to the positive direction of axis 1. If the Frame has more than 2 +* axes, a positive value will always be returned in the range zero +* to $\pi$. + +* Notes: +* - The geodesic curve used by this function is the path of +* shortest distance between two points, as defined by the +* astDistance function. +* - This function will return "bad" coordinate values (AST__BAD) +* if any of the input coordinates has this value, or if the require +* position angle is undefined. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double result; /* Value to return */ + +/* Check the global error status. */ + if ( !astOK ) return AST__BAD; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis - 1, 1, "astAxAngle" ); + +/* Obtain a pointer to the Region's encapsulated Frame and invoke the + astAxAngle method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astAxAngle( fr, a, b, axis ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = AST__BAD; + +/* Return the result. */ + return result; +} + +static double AxDistance( AstFrame *this_frame, int axis, double v1, double v2, int *status ) { +/* +* Name: +* AxDistance + +* Purpose: +* Find the distance between two axis values. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* double AxDistance( AstFrame *this, int axis, double v1, double v2, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astAxDistance +* method inherited from the Frame class). + +* Description: +* This function returns a signed value representing the axis increment +* from axis value v1 to axis value v2. +* +* For a simple Frame, this is a trivial operation returning the +* difference between the two axis values. But for other derived classes +* of Frame (such as a SkyFrame) this is not the case. + +* Parameters: +* this +* Pointer to the Frame. +* axis +* The index of the axis to which the supplied values refer. The +* first axis has index 1. +* v1 +* The first axis value. +* v2 +* The second axis value. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The distance between the two axis values. + +* Notes: +* - This function will return a "bad" result value (AST__BAD) if +* any of the input vaues has this value. +* - A "bad" value will also be returned if this function is +* invoked with the AST error status set, or if it should fail for +* any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double result; /* Value to return */ + +/* Check the global error status. */ + if ( !astOK ) return AST__BAD; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis - 1, 1, "astAxDistance" ); + +/* Obtain a pointer to the Region's encapsulated Frame and invoke the + astAxDistance method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astAxDistance( fr, axis, v1, v2 ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = AST__BAD; + +/* Return the result. */ + return result; +} + +static void AxNorm( AstFrame *this_frame, int axis, int oper, int nval, + double *values, int *status ){ +/* +* Name: +* AxNorm + +* Purpose: +* Normalise an array of axis values. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void AxNorm( AstFrame *this, int axis, int oper, int nval, +* double *values, int *status ) + +* Class Membership: +* FrameSet member function (over-rides the protected astAxNorm +* method inherited from the Frame class). + +* Description: +* This function modifies a supplied array of axis values so that +* they are normalised in the manner indicated by parameter "oper". +* +* No normalisation is possible for a simple Frame and so the supplied +* values are returned unchanged. However, this may not be the case for +* specialised sub-classes of Frame. For instance, a SkyFrame has a +* discontinuity at zero longitude and so a longitude value can be +* expressed in the range [-Pi,+PI] or the range [0,2*PI]. + +* Parameters: +* this +* Pointer to the Frame. +* axis +* The index of the axis to which the supplied values refer. The +* first axis has index 1. +* oper +* Indicates the type of normalisation to be applied. If zero is +* supplied, the normalisation will be the same as that performed by +* function astNorm. If 1 is supplied, the normalisation will be +* chosen automatically so that the resulting list has the smallest +* range. +* nval +* The number of points in the values array. +* values +* On entry, the axis values to be normalised. Modified on exit to +* hold the normalised values. +* status +* Pointer to the inherited status variable. + +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis - 1, 1, "astAxNorm" ); + +/* Obtain a pointer to the Region's encapsulated Frame and invoke + the astAxNorm method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astAxNorm( fr, axis, oper, nval, values ); + fr = astAnnul( fr ); +} + +static double AxOffset( AstFrame *this_frame, int axis, double v1, double dist, int *status ) { +/* +* Name: +* AxOffset + +* Purpose: +* Add an increment onto a supplied axis value. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* double AxOffset( AstFrame *this, int axis, double v1, double dist, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astAxOffset +* method inherited from the Frame class). + +* Description: +* This function returns an axis value formed by adding a signed axis +* increment onto a supplied axis value. +* +* For a simple Frame, this is a trivial operation returning the +* sum of the two supplied values. But for other derived classes +* of Frame (such as a SkyFrame) this is not the case. + +* Parameters: +* this +* Pointer to the Frame. +* axis +* The index of the axis to which the supplied values refer. The +* first axis has index 1. +* v1 +* The original axis value. +* dist +* The axis increment to add to the original axis value. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The incremented axis value. + +* Notes: +* - This function will return a "bad" result value (AST__BAD) if +* any of the input vaues has this value. +* - A "bad" value will also be returned if this function is +* invoked with the AST error status set, or if it should fail for +* any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double result; /* Value to return */ + +/* Check the global error status. */ + if ( !astOK ) return AST__BAD; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis - 1, 1, "astAxOffset" ); + +/* Obtain a pointer to the Region's encapsulated Frame and invoke the + astAxOffset method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astAxOffset( fr, axis, v1, dist ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = AST__BAD; + +/* Return the result. */ + return result; +} + +static AstPointSet *BndBaseMesh( AstRegion *this, double *lbnd, double *ubnd, int *status ){ +/* +*+ +* Name: +* astBndBaseMesh + +* Purpose: +* Return a PointSet containing points spread around part of the boundary +* of a Region, in the base Frame. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstPointSet *astBndBaseMesh( AstRegion *this, double *lbnd, double *ubnd ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a PointSet containing a set of points on the +* boundary of the intersection between the supplied Region and the +* supplied (current Frame) box. The mesh points refer to the base +* Frame. If the boundary of the supplied Region does not intersect the +* supplied box, then a PointSet containing a single bad point is +* returned. + +* Parameters: +* this +* Pointer to the Region. +* lbnd +* Pointer to an array holding the lower limits of the axis values +* within the required box. Defined in the current Frame of the Region. +* ubnd +* Pointer to an array holding the upper limits of the axis values +* within the required box. Defined in the current Frame of the Region. + +* Returned Value: +* Pointer to the PointSet holding the base Frame mesh. The axis values +* in this PointSet will have associated accuracies derived from the +* uncertainties which were supplied when the Region was created. +* +* If the Region does not intersect the supplied box, the returned +* PointSet will contain a single point with a value of AST__BAD on +* every axis. + +* Notes: +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. +*- +*/ + +/* Local Variables: */ + AstBox *box; + AstCmpRegion *cmpreg; + AstPointSet *result; + double **ptr; + int ic; + int nc; + +/* Check the local error status. */ + if ( !astOK ) return NULL; + +/* Form a Box describing the required box. */ + box = astBox( this, 1, lbnd, ubnd, NULL, "", status ); + +/* Check there is partial overlap between the Regions.*/ + if( astOverlap( this, box ) > 3 ) { + +/* Form a CmpRegion representing the intersection between the supplied + Region and the above box. */ + cmpreg = astCmpRegion( this, box, AST__AND, "", status ); + +/* Get the boundary mesh. */ + result = astRegBaseMesh( cmpreg ); + +/* Free resources. */ + cmpreg = astAnnul( cmpreg ); + +/* If the boundary of the supplied Region does not intersect the box, + return a PointSet containing a single bad position. */ + } else { + nc = astGetNin( this->frameset ); + result = astPointSet( 1, nc, "", status ); + ptr = astGetPoints( result ); + if( ptr ) { + for( ic = 0; ic < nc; ic++ ) ptr[ ic ][ 0 ] = AST__BAD; + } + } + +/* Free resources. */ + box = astAnnul( box ); + +/* Return NULL if an error occurred. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the required pointer. */ + return result; +} + +static AstPointSet *BndMesh( AstRegion *this, double *lbnd, double *ubnd, int *status ){ +/* +*+ +* Name: +* astBndMesh + +* Purpose: +* Return a PointSet containing points spread around part of the boundary +* of a Region, in the current Frame. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstPointSet *astBndMesh( AstRegion *this, double *lbnd, double *ubnd ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a PointSet containing a set of points on the +* boundary of the intersection between the supplied Region and the +* supplied box. The points refer to the current Frame of the +* encapsulated FrameSet. If the boundary of the supplied Region does +* not intersect the supplied box, then a PointSet containing a single +* bad point is returned. + +* Parameters: +* this +* Pointer to the Region. +* lbnd +* Pointer to an array holding the lower limits of the axis values +* within the required box. Defined in the current Frame of the Region. +* ubnd +* Pointer to an array holding the upper limits of the axis values +* within the required box. Defined in the current base Frame of the +* Region. + +* Returned Value: +* Pointer to the PointSet. The axis values in this PointSet will have +* associated accuracies derived from the uncertainties which were +* supplied when the Region was created. +* +* If the Region does not intersect the supplied box, the returned +* PointSet will contain a single point with a value of AST__BAD on +* every axis. + +* Notes: +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. +*- +*/ + +/* Local Variables: */ + AstMapping *map; + AstPointSet *ps1; + AstPointSet *result; + +/* Initialise */ + result = NULL; + +/* Check the local error status. */ + if ( !astOK ) return result; + +/* Get the current->base Mapping from the Region. */ + map = astGetMapping( this->frameset, AST__CURRENT, AST__BASE ); + +/* Use astBndBaseMesh to get a mesh of base Frame points within this base + Frame bounding box. */ + ps1 = astBndBaseMesh( this, lbnd, ubnd ); + +/* Transform it into the current Frame. */ + if( ps1 ) result = astTransform( map, ps1, 0, NULL ); + +/* Free resources. */ + map = astAnnul( map ); + ps1 = astAnnul( ps1 ); + +/* Return NULL if an error occurred. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the required pointer. */ + return result; +} + +static AstPointSet *BTransform( AstRegion *this, AstPointSet *in, + int forward, AstPointSet *out, int *status ) { +/* +*+ +* Name: +* astBTransform + +* Purpose: +* Use a Region to transform a set of points in the base Frame. + +* Type: +* Protected virtual function. + +* Synopsis: +* #include "circle.h" +* AstPointSet *astBTransform( AstRegion *this, AstPointSet *in, + int forward, AstPointSet *out ) + +* Class Membership: +* Region member function + +* Description: +* This function takes a Region and a set of points within the base +* Frame of the Region, and transforms the points by setting axis values +* to AST__BAD for all points which are outside the region. Points inside +* the region are copied unchanged from input to output. + +* Parameters: +* this +* Pointer to the Region. +* in +* Pointer to the PointSet holding the input coordinate data. +* forward +* A non-zero value indicates that the forward coordinate transformation +* should be applied, while a zero value requests the inverse +* transformation. +* out +* Pointer to a PointSet which will hold the transformed (output) +* coordinate values. A NULL value may also be given, in which case a +* new PointSet will be created by this function. + +* Returned Value: +* Pointer to the output (possibly new) PointSet. + +* Notes: +* - This is identical to the astTransform method for a Region except +* that the supplied and returned points refer to the base Frame of +* the Region, rather than the current Frame. +*- +*/ + +/* Local Variables: */ + AstPointSet *result; /* Pointer to output PointSet */ + int old; /* Origial value of "nomap" flag */ + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* Save the current value of the "nomap" flag for this Region,and then + set it. Doing this tells the astRegMapping function (called by + astRegTransform) to assume a unit map connects base and current Frame. */ + old = this->nomap; + this->nomap = 1; + +/* Invoke the usual astTransform method. The above setting of the "nomap" + flag will cause the astTransform method to treat the base Frame as the + current Frame. */ + result = astTransform( this, in, forward, out ); + +/* Reset the "nomap" flag. */ + this->nomap = old; + +/* Return a pointer to the output PointSet. */ + return result; +} + +static AstObject *Cast( AstObject *this_object, AstObject *obj, int *status ) { +/* +* Name: +* Cast + +* Purpose: +* Cast an Object into an instance of a sub-class. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstObject *Cast( AstObject *this, AstObject *obj, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astCast +* method inherited from the Frame class). + +* Description: +* This function returns a deep copy of an ancestral component of the +* supplied object. The required class of the ancestral component is +* specified by another object. Specifically, if "this" and "new" are +* of the same class, a copy of "this" is returned. If "this" is an +* instance of a subclass of "obj", then a copy of the component +* of "this" that matches the class of "obj" is returned. Otherwise, +* a NULL pointer is returned without error. + +* Parameters: +* this +* Pointer to the Object to be cast. +* obj +* Pointer to an Object that defines the class of the returned Object. +* The returned Object will be of the same class as "obj". + +* Returned Value: +* A pointer to the new Object. NULL if "this" is not a sub-class of +* "obj", or if an error occurs. + +* Notes: +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables; */ + AstFrame *cfrm; + AstObject *new; + astDECLARE_GLOBALS + int generation_gap; + +/* Initialise */ + new = NULL; + +/* Check inherited status */ + if( !astOK ) return new; + +/* Get a pointer to the thread specific global data structure. */ + astGET_GLOBALS(NULL); + +/* See how many steps up the class inheritance ladder it is from "obj" + to this class (Region). A positive value is returned if Region is + a sub-class of "obj". A negative value is returned if "obj" is a + sub-class of Region. Zero is returned if "obj" is a Region. + AST__COUSIN is returned if "obj" is not on the same line of descent + as Region. */ + generation_gap = astClassCompare( (AstObjectVtab *) &class_vtab, + astVTAB( obj ) ); + +/* If "obj" is a Region or a sub-class of Region, we can cast by + truncating the vtab for "this" so that it matches the vtab of "obJ", + and then taking a deep copy of "this". */ + if( generation_gap <= 0 && generation_gap != AST__COUSIN ) { + new = astCastCopy( this_object, obj ); + +/* If "obj" is not a Region or a sub-class of Region (e.g. a Frame or + some sub-class of Frame), we attempt to cast the current Frame of the + encapsulated FrameSet into the class indicated by "obj". */ + } else { + cfrm = astGetFrame( ((AstRegion *) this_object)->frameset, AST__CURRENT ); + new = astCast( cfrm, obj ); + cfrm = astAnnul( cfrm ); + } + +/* Return the new pointer. */ + return new; +} + +static double Centre( AstFrame *this_frame, int axis, double value, double gap, int *status ) { +/* +* Name: +* Centre + +* Purpose: +* Find a "nice" central value for tabulating Frame axis values. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* double Centre( AstFrame *this_frame, int axis, double value, +* double gap, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astCentre method +* inherited from the Frame class). + +* Description: +* This function returns an axis value which produces a nice formatted +* value suitable for a major tick mark on a plot axis, close to the +* supplied axis value. + +* Parameters: +* this +* Pointer to the Frame. +* axis +* The number of the axis (zero-based) for which a central value +* is to be found. +* value +* An arbitrary axis value in the section that is being plotted. +* gap +* The gap size. + +* Returned Value: +* The nice central axis value. + +* Notes: +* - A value of zero is returned if the supplied gap size is zero. +* - A value of zero will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double result; /* Value to return */ + +/* Check the global error status. */ + if ( !astOK ) return 0.0; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis, 1, "astCentre" ); + +/* Obtain a pointer to the Region's current Frame and invoke this + Frame's astCentre method to obtain the required value. Annul the + Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astCentre( fr, axis, value, gap ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result. */ + if ( !astOK ) result = 0.0; + +/* Return the result. */ + return result; +} + +static void CheckPerm( AstFrame *this_frame, const int *perm, const char *method, int *status ) { +/* +* Name: +* CheckPerm + +* Purpose: +* Check that an array contains a valid permutation. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void CheckPerm( AstFrame *this, const int *perm, const char *method, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astCheckPerm +* method inherited from the Frame class). + +* Description: +* This function checks the validity of a permutation array that +* will be used to permute the order of a Frame's axes. If the +* permutation specified by the array is not valid, an error is +* reported and the global error status is set. Otherwise, the +* function returns without further action. + +* Parameters: +* this +* Pointer to the Frame. +* perm +* Pointer to an array of integers with the same number of +* elements as there are axes in the Frame. For each axis, the +* corresponding integer gives the (zero based) axis index to be +* used to identify the information for that axis (using the +* un-permuted axis numbering). To be valid, the integers in +* this array should therefore all lie in the range zero to +* (naxes-1) inclusive, where "naxes" is the number of Frame +* axes, and each value should occur exactly once. +* method +* Pointer to a constant null-terminated character string +* containing the name of the method that invoked this function +* to validate a permutation array. This method name is used +* solely for constructing error messages. +* status +* Pointer to the inherited status variable. + +* Notes: +* - Error messages issued by this function refer to the external +* (public) numbering system used for axes (which is one-based), +* whereas zero-based axis indices are used internally. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke this + Frame's astCheckPerm method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astCheckPerm( fr, perm, method ); + fr = astAnnul( fr ); + +} + +static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { +/* +* Name: +* ClearAttrib + +* Purpose: +* Clear an attribute value for a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void ClearAttrib( AstObject *this, const char *attrib, int *status ) + +* Class Membership: +* Region member function (over-rides the astClearAttrib protected +* method inherited from the Frame class). + +* Description: +* This function clears the value of a specified attribute for a +* Region, so that the default value will subsequently be used. + +* Parameters: +* this +* Pointer to the Region. +* attrib +* Pointer to a null terminated string specifying the attribute +* name. This should be in lower case with no surrounding white +* space. +* status +* Pointer to the inherited status variable. +*/ + +/* Local Variables: */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_object; + +/* Check the attribute name and clear the appropriate attribute. */ + +/* We first handle attributes that apply to the Region as a whole + (rather than to the encapsulated FrameSet). */ + +/* Negated */ +/* ------- */ + if ( !strcmp( attrib, "negated" ) ) { + astClearNegated( this ); + +/* Closed */ +/* ------ */ + } else if ( !strcmp( attrib, "closed" ) ) { + astClearClosed( this ); + +/* FillFactor */ +/* ---------- */ + } else if ( !strcmp( attrib, "fillfactor" ) ) { + astClearFillFactor( this ); + +/* MeshSize */ +/* -------- */ + } else if ( !strcmp( attrib, "meshsize" ) ) { + astClearMeshSize( this ); + +/* Adaptive */ +/* -------- */ + } else if ( !strcmp( attrib, "adaptive" ) ) { + astClearAdaptive( this ); + + +/* We now check for atttributes of superclasses which apply to the Region + as a whole. We do not want to pass these on to the encapsulated FrameSet. */ + +/* ID. */ +/* --- */ + } else if ( !strcmp( attrib, "id" ) ) { + astClearID( this ); + +/* Ident. */ +/* ------ */ + } else if ( !strcmp( attrib, "ident" ) ) { + astClearIdent( this ); + +/* Invert. */ +/* ------- */ + } else if ( !strcmp( attrib, "invert" ) ) { + astClearInvert( this ); + +/* Report. */ +/* ------- */ + } else if ( !strcmp( attrib, "report" ) ) { + astClearReport( this ); + + +/* If the name was not recognised, test if it matches any of the + read-only attributes of this class (including those of all superclasses). + If it does, then report an error. */ + } else if ( !strcmp( attrib, "class" ) || + !strcmp( attrib, "nin" ) || + !strcmp( attrib, "nobject" ) || + !strcmp( attrib, "nout" ) || + !strcmp( attrib, "bounded" ) || + !strcmp( attrib, "refcount" ) || + !strcmp( attrib, "tranforward" ) || + !strcmp( attrib, "traninverse" ) ) { + astError( AST__NOWRT, "astClear: Invalid attempt to clear the \"%s\" " + "value for a %s.", status, attrib, astGetClass( this ) ); + astError( AST__NOWRT, "This is a read-only attribute." , status); + +/* Pass unrecognised attributes on to the Region's encapsulated FrameSet for + further interpretation. Do not pass on FrameSet attributes since we + pretend to the outside world that the encapsulated FrameSet is actually a + Frame. */ + } else if ( strcmp( attrib, "base" ) && + strcmp( attrib, "current" ) && + strcmp( attrib, "nframe" ) ) { + +/* If the Region is to adapt to coordinate system chanmges, use the public + astClear method so that the current Frame in the encapsulated FrameSet will + be re-mapped if the attribute changes require it. */ + if( astGetAdaptive( this ) ) { + astClear( this->frameset, attrib ); + +/* If the Region is not to adapt to coordinate system chanmges, use the + astRegSetAttrib method which assigns the attribute setting to both + current and base Frames in the FrameSet without causing any remapping to + be performed. */ + } else { + astRegClearAttrib( this, attrib, NULL ); + } + } +} + +static AstFrameSet *Conv( AstFrameSet *from, AstFrameSet *to, int *status ){ +/* +* Name: +* Conv + +* Purpose: +* Find Mapping between Frames + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstFrameSet *Conv( AstFrameSet *from, AstFrameSet *to, int *status ); + +* Class Membership: +* Region member function + +* Description: +* This function provides a convenient interface for astConvert. +* It is like astConvert except it does not alter the base Frames of +* the supplied FrameSets and does not require a Domain list. + +* Parameters: +* from +* Pointer to the source FrameSet. +* to +* Pointer to the source FrameSet. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The conversion FrameSet (see astConvert). + +*/ + +/* Local Variables: */ + AstFrameSet *result; /* FrameSet to return */ + int from_base; /* Index of original base Frame in "from" */ + int to_base; /* Index of original base Frame in "to" */ + +/* Check the global error status. */ + if( !astOK ) return NULL; + +/* Note the indices of the base Frames in the FrameSets. */ + to_base = astGetBase( to ); + from_base = astGetBase( from ); + +/* Invoke astConvert. */ + result = astConvert( from, to, "" ); + +/* Re-instate original base Frames. */ + astSetBase( to, to_base ); + astSetBase( from, from_base ); + +/* Return the result. */ + return result; +} + +static AstFrameSet *Convert( AstFrame *from, AstFrame *to, + const char *domainlist, int *status ) { +/* +* Name: +* Convert + +* Purpose: +* Determine how to convert between two coordinate systems. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstFrameSet *Convert( AstFrame *from, AstFrame *to, +* const char *domainlist, int *status ) + +* Class Membership: +* Region member function (over-rides the public astConvert +* method inherited fromm the Frame class). + +* Description: +* This function compares two Regions and determines whether it +* is possible to convert between the coordinate systems which +* their current Frames represent. If conversion is possible, it +* returns a FrameSet which describes the conversion and which may +* be used (as a Mapping) to transform coordinate values in either +* direction. + +* Parameters: +* from +* Pointer to a Region whose current Frame represents the +* "source" coordinate system. Note that the Base attribute of +* the Region may be modified by this function. +* to +* Pointer to a Region whose current Frame represents the +* "destination" coordinate system. Note that the Base +* attribute of the Region may be modified by this function. +* domainlist +* Pointer to a null-terminated character string containing a +* comma-separated list of Frame domains. This may be used to +* define a priority order for the different intermediate +* coordinate systems that might be used to perform the +* conversion. +* +* The function will first try to obtain a conversion by making +* use only of intermediate Frames whose Domain attribute +* matches the first domain in this list. If this fails, the +* second domain in the list will be used, and so on, until +* conversion is achieved. A blank domain (e.g. two consecutive +* commas) indicates that all Frames should be considered, +* regardless of their Domain attributes. The list is +* case-insensitive and all white space is ignored. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* If the requested coordinate conversion is possible, the +* function returns a pointer to a FrameSet which describes the +* conversion. Otherwise, a null Object pointer (AST__NULL) is +* returned without error. +* +* If a FrameSet is returned, it will contain two Frames. Frame +* number 1 (its base Frame) will describe the source coordinate +* system, corresponding to the "from" parameter. Frame number 2 +* (its current Frame) will describe the destination coordinate +* system, corresponding to the "to" parameter. The Mapping +* which inter-relates these Frames will perform the required +* conversion between the two coordinate systems. + +* Notes: +* - The returned FrameSet will not contain any Regions. If one or +* more of the supplied Frames are in fact Regions, the corresponding +* Frames in any returned FrameSet will described the encapsulated +* Frame, without any region information. +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrameSet *result; /* Returned FrameSet */ + +/* Check the inherited status. */ + if ( !astOK ) return NULL; + +/* If the "from" pointer is a Region, get a pointer to the current Frame of + the encapsulated FrameSet and use it instead of the supplied pointer. */ + if( astIsARegion( from ) ) { + from = astGetFrame( ((AstRegion *) from)->frameset, AST__CURRENT ); + } else { + from = astClone( from ); + } + +/* If the "to" pointer is a Region, get a pointer to the current Frame of + the encapsulated FrameSet and use it instead of the supplied pointer. */ + if( astIsARegion( to ) ) { + to = astGetFrame( ((AstRegion *) to)->frameset, AST__CURRENT ); + } else { + to = astClone( to ); + } + +/* Now invoke astConvert on the above Frames. */ + result = astConvert( from, to, domainlist ); + +/* Annul the pointers used above. */ + from = astAnnul( from ); + to = astAnnul( to ); + +/* Return the result */ + return result; +} + +static AstFrameSet *ConvertX( AstFrame *to, AstFrame *from, + const char *domainlist, int *status ) { +/* +* Name: +* ConvertX + +* Purpose: +* Determine how to convert between two coordinate systems. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstFrameSet *astConvertX( AstFrame *to, AstFrame *from, +* const char *domainlist ) + +* Class Membership: +* Region member function (over-rides the protected astConvertX +* method inherited from the Frame class). + +* Description: +* This function performs the processing for the public astConvert +* method and has exactly the same interface except that the order +* of the first two arguments is swapped. This is a trick to allow +* the astConvert method to be over-ridden by derived classes on +* the basis of the class of either of its first two arguments. +* +* See the astConvert method for details of the interface. +*- +*/ + +/* Local Variables: */ + AstFrameSet *result; /* Returned FrameSet */ + +/* Check the inherited status. */ + if ( !astOK ) return NULL; + +/* If the "to" pointer is a Region, get a pointer to the current Frame of + the encapsulated FrameSet and use it instead of the supplied pointer. */ + if( astIsARegion( to ) ) { + to = astGetFrame( ((AstRegion *) to)->frameset, AST__CURRENT ); + } else { + to = astClone( to ); + } + +/* If the "from" pointer is a Region, get a pointer to the current Frame of + the encapsulated FrameSet and use it instead of the supplied pointer. */ + if( astIsARegion( from ) ) { + from = astGetFrame( ((AstRegion *) from)->frameset, AST__CURRENT ); + } else { + from = astClone( from ); + } + +/* Now invoke astConvertX on the above Frames. */ + result = astConvertX( to, from, domainlist ); + +/* Annul the pointers used above. */ + from = astAnnul( from ); + to = astAnnul( to ); + +/* Return the result */ + return result; +} + +static double Distance( AstFrame *this_frame, const double point1[], + const double point2[], int *status ) { +/* +* Name: +* Distance + +* Purpose: +* Calculate the distance between two points. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* double Distance( AstFrame *this, const double point1[], +* const double point2[], int *status ) + +* Class Membership: +* Region member function (over-rides the protected astDistance +* method inherited from the Frame class). + +* Description: +* This function finds the distance between two points whose +* Region coordinates are given. The distance calculated is that +* along the geodesic curve that joins the two points. + +* Parameters: +* this +* Pointer to the Region. +* point1 +* An array of double, with one element for each Region axis +* containing the coordinates of the first point. +* point2 +* An array of double, with one element for each Region axis +* containing the coordinates of the second point. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The distance between the two points. + +* Notes: +* - This function will return a "bad" result value (AST__BAD) if +* any of the input coordinates has this value. +* - A "bad" value will also be returned if this function is +* invoked with the AST error status set or if it should fail for +* any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double result; /* Value to return */ + +/* Check the global error status. */ + if ( !astOK ) return AST__BAD; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's current Frame and invoke this + Frame's astDistance method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astDistance( fr, point1, point2 ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result. */ + if ( !astOK ) result = AST__BAD; + +/* Return the result. */ + return result; +} + +static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { +/* +* Name: +* Equal + +* Purpose: +* Test if two Objects are equivalent. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int Equal( AstObject *this_object, AstObject *that_object, int *status ) + +* Class Membership: +* Region member function (over-rides the astEqual protected +* method inherited from the Frame class). + +* Description: +* This function returns a boolean result (0 or 1) to indicate whether +* two Regions are equivalent. + +* Parameters: +* this +* Pointer to the first Region. +* that +* Pointer to the second Region. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* One if the Regions are equivalent, zero otherwise. + +* Notes: +* - The Regions are equivalent if they are of the same class, have +* equal PointSets, have equal base Frames, have equal current Frames, +* and if the Mapping between base Frames is a UnitMap. In addition, the +* Negated attribute must have the same value in both Regions, as must +* the Closed attribute. +* - A value of zero will be returned if this function is invoked +* with the global status set, or if it should fail for any reason. +*/ + +/* Local Variables: */ + AstFrame *bf1; + AstFrame *bf2; + AstFrame *cf1; + AstFrame *cf2; + AstMapping *m1; + AstMapping *m2; + AstRegion *that; + AstRegion *this; + const char *class1; + const char *class2; + int result; + +/* Initialise. */ + result = 0; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Check that the two objects have the same class. */ + class1 = astGetClass( this_object ); + class2 = astGetClass( that_object ); + if( astOK && !strcmp( class1, class2 ) ) { + +/* Obtain pointers to the two Region structures. */ + this = (AstRegion *) this_object; + that = (AstRegion *) that_object; + +/* Test their PointSets for equality. */ + if( astEqual( this->points, that->points ) ){ + +/* Test their base Frames for equality. */ + bf1 = astGetFrame( this->frameset, AST__BASE ); + bf2 = astGetFrame( that->frameset, AST__BASE ); + if( astEqual( bf1, bf2 ) ){ + +/* Test their current Frames for equality. */ + cf1 = astGetFrame( this->frameset, AST__CURRENT ); + cf2 = astGetFrame( that->frameset, AST__CURRENT ); + if( astEqual( cf1, cf2 ) ){ + +/* Get the two Mappings and check that they are equal */ + m1 = astGetMapping( this->frameset, AST__BASE, AST__CURRENT ); + m2 = astGetMapping( that->frameset, AST__BASE, AST__CURRENT ); + if( astEqual( m1, m2 ) ) { + +/* Test the Negated and Closed flags are equal */ + if( astGetNegated( this ) == astGetNegated( that ) && + astGetClosed( this ) == astGetClosed( that ) ) { + result = 1; + } + } + +/* Free resources. */ + m1 = astAnnul( m1 ); + m2 = astAnnul( m2 ); + } + + cf1 = astAnnul( cf1 ); + cf2 = astAnnul( cf2 ); + } + + bf1 = astAnnul( bf1 ); + bf2 = astAnnul( bf2 ); + } + } + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = 0; + +/* Return the result, */ + return result; +} + +static void ClearUnc( AstRegion *this, int *status ){ +/* +*+ +* Name: +* astClearUnc + +* Purpose: +* Erase any uncertainty information in a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astClearUnc( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function erases all uncertainty information, whether default +* or not, from a Region. + +* Parameters: +* this +* Pointer to the Region. + +*- +*/ + +/* Check the inherited status. */ + if( !astOK ) return; + +/* Annul any user-supplied uncertainty. Also indicate that cached + information may now be out of date. */ + if( this->unc ) { + this->unc = astAnnul( this->unc ); + astResetCache( this ); + } + +/* Annul any default uncertainty. */ + if( this->defunc ) this->defunc = astAnnul( this->defunc ); + +} + +static AstFrameSet *FindFrame( AstFrame *target_frame, AstFrame *template, + const char *domainlist, int *status ) { +/* +* Name: +* FindFrame + +* Purpose: +* Find a coordinate system with specified characteristics. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstFrameSet *FindFrame( AstFrame *target, AstFrame *template, +* const char *domainlist, int *status ) + +* Class Membership: +* Region member function (over-rides the astFindFrame method +* inherited from the Frame class). + +* Description: +* This function uses a "template" Frame to search a Region to +* identify a coordinate system which has a specified set of +* characteristics. If a suitable coordinate system can be found, +* the function returns a pointer to a FrameSet which describes the +* required coordinate system and how to convert coordinates to and +* from it. + +* Parameters: +* target +* Pointer to the target Region. +* template +* Pointer to the template Frame, which should be an instance of +* the type of Frame you wish to find. +* domainlist +* Pointer to a null-terminated character string containing a +* comma-separated list of Frame domains. This may be used to +* establish a priority order for the different types of +* coordinate system that might be found. +* +* The function will first try to find a suitable coordinate +* system whose Domain attribute equals the first domain in this +* list. If this fails, the second domain in the list will be +* used, and so on, until a result is obtained. A blank domain +* (e.g. two consecutive commas) indicates that any coordinate +* system is acceptable (subject to the template) regardless of +* its domain. +* +* This list is case-insensitive and all white space is ignored. +* If you do not wish to restrict the domain in this way, you +* should supply an empty string. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* If the search is successful, the function returns a pointer to a +* FrameSet which contains the Frame found and a description of how +* to convert to (and from) the coordinate system it +* represents. Otherwise, a null Object pointer (AST__NULL) is +* returned without error. +* +* If a FrameSet is returned, it will contain two Frames. Frame +* number 1 (its base Frame) represents the target coordinate +* system and will be the same as the target. Frame number 2 (its +* current Frame) will be a Frame representing the coordinate system +* which the function found. The Mapping which inter-relates these two +* Frames will describe how to convert between their respective coordinate +* systems. Note, the Frames in this FrameSet will not be Regions - +* that is, they will be simple Frames or other derived classes. + +* Notes: +* - A null Object pointer (AST__NULL) will be returned if this +* function is invoked with the AST error status set, or if it +* should fail for any reason. +*/ + +/* Local Variables: */ + AstFrameSet *result; /* Pointer to result FrameSet */ + AstFrame *fr; /* Pointer to encapsulated Frame */ + +/* Initialise. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Invoke the astFindFrame method on the current Frame of the + encapsulated FrameSet within the target Region. */ + fr = astGetFrame( ((AstRegion *) target_frame)->frameset, AST__CURRENT ); + result = astFindFrame( fr, template, domainlist ); + fr = astAnnul( fr ); + +/* Return the result. */ + return result; +} + +static const char *Format( AstFrame *this_frame, int axis, double value, int *status ) { +/* +* Name: +* Format + +* Purpose: +* Format a coordinate value for a Region axis. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* const char *Format( AstFrame *this, int axis, double value, int *status ) + +* Class Membership: +* Region member function (over-rides the astFormat method +* inherited from the Frame class). + +* Description: +* This function returns a pointer to a string containing the +* formatted (character) version of a coordinate value for a +* Region axis. The formatting applied is that specified by a +* previous invocation of the astSetFormat method. A suitable +* default format is applied if necessary. + +* Parameters: +* this +* Pointer to the Region. +* axis +* The number of the axis (zero-based) for which formatting is +* to be performed. +* value +* The coordinate value to be formatted. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A pointer to a null-terminated string containing the formatted +* value. + +* Notes: +* - The returned string pointer may point at memory allocated +* within the Region object, or at static memory. The contents of +* the string may be over-written or the pointer may become invalid +* following a further invocation of the same function or deletion +* of the Region. A copy of the string should therefore be made +* if necessary. +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + const char *result; /* Pointer value to return */ + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis, 1, "astFormat" ); + +/* Obtain a pointer to the Region's current Frame and invoke the + astFormat method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astFormat( fr, axis, value ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = NULL; + +/* Return the result. */ + return result; +} + +static double Gap( AstFrame *this_frame, int axis, double gap, int *ntick, int *status ) { +/* +* Name: +* Gap + +* Purpose: +* Find a "nice" gap for tabulating Region axis values. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* double Gap( AstFrame *this, int axis, double gap, int *ntick, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astGap method +* inherited from the Frame class). + +* Description: +* This function returns a gap size which produces a nicely spaced +* series of formatted values for a Region axis, the returned gap +* size being as close as possible to the supplied target gap +* size. It also returns a convenient number of divisions into +* which the gap can be divided. + +* Parameters: +* this +* Pointer to the Region. +* axis +* The number of the axis (zero-based) for which a gap is to be found. +* gap +* The target gap size. +* ntick +* Address of an int in which to return a convenient number of +* divisions into which the gap can be divided. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The nice gap size. + +* Notes: +* - A value of zero is returned if the target gap size is zero. +* - A negative gap size is returned if the supplied gap size is negative. +* - A value of zero will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double result; /* Gap value to return */ + +/* Check the global error status. */ + if ( !astOK ) return 0.0; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis, 1, "astGap" ); + +/* Obtain a pointer to the Region's current Frame and invoke this + Frame's astGap method to obtain the required gap value. Annul the + Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astGap( fr, axis, gap, ntick ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result. */ + if ( !astOK ) result = 0.0; + +/* Return the result. */ + return result; +} + +static int GetObjSize( AstObject *this_object, int *status ) { +/* +* Name: +* GetObjSize + +* Purpose: +* Return the in-memory size of an Object. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int GetObjSize( AstObject *this, int *status ) + +* Class Membership: +* Region member function (over-rides the astGetObjSize protected +* method inherited from the parent class). + +* Description: +* This function returns the in-memory size of the supplied Region, +* in bytes. + +* Parameters: +* this +* Pointer to the Region. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The Object size, in bytes. + +* Notes: +* - A value of zero will be returned if this function is invoked +* with the global status set, or if it should fail for any reason. +*/ + +/* Local Variables: */ + AstRegion *this; /* Pointer to Region structure */ + int result; /* Result value to return */ + +/* Initialise. */ + result = 0; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointers to the Region structure. */ + this = (AstRegion *) this_object; + +/* Invoke the GetObjSize method inherited from the parent class, and then + add on any components of the class structure defined by thsi class + which are stored in dynamically allocated memory. */ + result = (*parent_getobjsize)( this_object, status ); + + result += astGetObjSize( this->frameset ); + result += astGetObjSize( this->points ); + result += astGetObjSize( this->basemesh ); + result += astGetObjSize( this->basegrid ); + result += astGetObjSize( this->unc ); + result += astGetObjSize( this->negation ); + result += astGetObjSize( this->defunc ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = 0; + +/* Return the result, */ + return result; +} + +static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { +/* +* Name: +* GetAttrib + +* Purpose: +* Get the value of a specified attribute for a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* const char *GetAttrib( AstObject *this, const char *attrib, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astGetAttrib +* method inherited from the Frame class). + +* Description: +* This function returns a pointer to the value of a specified +* attribute for a Region, formatted as a character string. + +* Parameters: +* this +* Pointer to the Region. +* attrib +* Pointer to a null-terminated string containing the name of +* the attribute whose value is required. This name should be in +* lower case, with all white space removed. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* - Pointer to a null-terminated string containing the attribute +* value. + +* Notes: +* - The returned string pointer may point at memory allocated +* within the Region, or at static memory. The contents of the +* string may be over-written or the pointer may become invalid +* following a further invocation of the same function or any +* modification of the Region. A copy of the string should +* therefore be made if necessary. +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + astDECLARE_GLOBALS /* Pointer to thread-specific global data */ + AstRegion *this; /* Pointer to the Region structure */ + const char *result; /* Pointer value to return */ + double dval; /* Floating point attribute value */ + int ival; /* Integer attribute value */ + +/* Initialise. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Get a pointer to the thread specific global data structure. */ + astGET_GLOBALS(this_object); + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_object; + +/* Compare "attrib" with each recognised attribute name in turn, + obtaining the value of the required attribute. If necessary, write + the value into "getattrib_buff" as a null-terminated string in an appropriate + format. Set "result" to point at the result string. */ + +/* We first handle attributes that apply to the Region as a whole + (rather than to the encapsulated FrameSet). */ + +/* Negated */ +/* ------- */ + if ( !strcmp( attrib, "negated" ) ) { + ival = astGetNegated( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Closed */ +/* ------ */ + } else if ( !strcmp( attrib, "closed" ) ) { + ival = astGetClosed( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Adaptive */ +/* -------- */ + } else if ( !strcmp( attrib, "adaptive" ) ) { + ival = astGetAdaptive( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* FillFactor */ +/* ---------- */ + } else if ( !strcmp( attrib, "fillfactor" ) ) { + dval = astGetFillFactor( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%.*g", AST__DBL_DIG, dval ); + result = getattrib_buff; + } + +/* MeshSize */ +/* -------- */ + } else if ( !strcmp( attrib, "meshsize" ) ) { + ival = astGetMeshSize( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Bounded */ +/* ------- */ + } else if ( !strcmp( attrib, "bounded" ) ) { + ival = astGetBounded( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Now get the values of attributes inherited from parent classes. We do + this to avoid the request being passed on to the encapsulated FrameSet + below. */ + +/* Class. */ +/* ------ */ + } else if ( !strcmp( attrib, "class" ) ) { + result = astGetClass( this ); + +/* ID. */ +/* --- */ + } else if ( !strcmp( attrib, "id" ) ) { + result = astGetID( this ); + +/* Ident. */ +/* ------ */ + } else if ( !strcmp( attrib, "ident" ) ) { + result = astGetIdent( this ); + +/* Invert. */ +/* ------- */ + } else if ( !strcmp( attrib, "invert" ) ) { + ival = astGetInvert( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Nin. */ +/* ---- */ + } else if ( !strcmp( attrib, "nin" ) ) { + ival = astGetNin( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Nobject. */ +/* -------- */ + } else if ( !strcmp( attrib, "nobject" ) ) { + ival = astGetNobject( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Nout. */ +/* ----- */ + } else if ( !strcmp( attrib, "nout" ) ) { + ival = astGetNout( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* RefCount. */ +/* --------- */ + } else if ( !strcmp( attrib, "refcount" ) ) { + ival = astGetRefCount( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Report. */ +/* ------- */ + } else if ( !strcmp( attrib, "report" ) ) { + ival = astGetReport( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* TranForward. */ +/* ------------ */ + } else if ( !strcmp( attrib, "tranforward" ) ) { + ival = astGetTranForward( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* TranInverse. */ +/* ------------ */ + } else if ( !strcmp( attrib, "traninverse" ) ) { + ival = astGetTranInverse( this ); + if ( astOK ) { + (void) sprintf( getattrib_buff, "%d", ival ); + result = getattrib_buff; + } + +/* Pass unrecognised attributes on to the Region's encapsulated FrameSet for + further interpretation. Do not pass on FrameSet attributes since we + pretend to the outside world that the encapsulated FrameSet is actually a + Frame. */ + } else if ( strcmp( attrib, "base" ) && + strcmp( attrib, "current" ) && + strcmp( attrib, "nframe" ) ) { + result = astGetAttrib( this->frameset, attrib ); + } + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = NULL; + +/* Return the result. */ + return result; +} + +static int GetBounded( AstRegion *this, int *status ) { +/* +*+ +* Name: +* astGetBounded + +* Purpose: +* Is the Region bounded? + +* Type: +* Protected function. + +* Synopsis: +* int astGetBounded( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a flag indicating if the Region is bounded. +* The implementation provided by the base Region class is suitable +* for Region sub-classes representing the inside of a single closed +* curve (e.g. Circle, Ellipse, Box, etc). Other sub-classes (such as +* CmpRegion, PointList, etc ) may need to provide their own +* implementations. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* Non-zero if the Region is bounded. Zero otherwise. + +*- +*/ + +/* For Regions which are defined by one or more closed curves such as Circles, + Boxes, etc, the Region is bounded so long as it has not been negated. + Classes for which this is not true should over-ride this implementation. */ + return !astGetNegated( this ); +} + +static AstAxis *GetAxis( AstFrame *this_frame, int axis, int *status ) { +/* +* Name: +* GetAxis + +* Purpose: +* Obtain a pointer to a specified Axis from a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstAxis *GetAxis( AstFrame *this, int axis, int *status ) + +* Class Membership: +* Region member function (over-rides the astGetAxis method +* inherited from the Frame class). + +* Description: +* This function returns a pointer to the Axis object associated +* with one of the axes of the current Frame of a Region. This +* object describes the quantity which is represented along that +* axis. + +* Parameters: +* this +* Pointer to the Region. +* axis +* The number of the axis (zero-based) for which an Axis pointer +* is required. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A pointer to the requested Axis object. + +* Notes: +* - The reference count of the requested Axis object will be +* incremented by one to reflect the additional pointer returned by +* this function. +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstAxis *result; /* Pointer to Axis */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis, 1, "astGetAxis" ); + +/* Obtain a pointer to the Region's encapsulated FrameSet and invoke + this FrameSet's astGetAxis method to obtain the required Axis + pointer. */ + result = astGetAxis( this->frameset, axis ); + +/* If an error occurred, annul the result. */ + if ( !astOK ) result = astAnnul( result ); + +/* Return the result. */ + return result; +} + +static AstRegion *GetDefUnc( AstRegion *this, int *status ) { +/* +*+ +* Name: +* astGetDefUnc + +* Purpose: +* Obtain a pointer to the default uncertainty Region for a given Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstRegion *astGetDefUnc( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a pointer to a Region which represents the +* default uncertainty associated with a position on the boundary of the +* given Region. The returned Region refers to the base Frame within the +* FrameSet encapsulated by the supplied Region. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* A pointer to the Region. This should be annulled (using astAnnul) +* when no longer needed. + +* Notes: +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Local Variables: */ + AstFrame *bfrm; /* Base Frame of supplied Region */ + AstRegion *result; /* Returned pointer */ + double *lbnd; /* Ptr. to array holding axis lower bounds */ + double *ubnd; /* Ptr. to array holding axis upper bounds */ + double c; /* Central axis value */ + double hw; /* Half width of uncertainty interval */ + int i; /* Axis index */ + int nax; /* Number of base Frame axes */ + +/* Initialise */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Get a pointer to the base Frame in the supplied Region. */ + bfrm = astGetFrame( this->frameset, AST__BASE ); + +/* Get the number of base Frame axes. */ + nax = astGetNaxes( bfrm ); + +/* Get the base frame bounding box of the supplied Region. The astRegBaseBox + assumes the supplied Region has not been inverted. But if the Region + contains other Regions (e.g. a Prism or CmpRegion, etc) then this + assumption needs to be propagated to the component Regions, which + astRegBaseBox does not do. For this reason we use astRegBaseBox2 + instead. */ + lbnd = astMalloc( sizeof( double)*(size_t) nax ); + ubnd = astMalloc( sizeof( double)*(size_t) nax ); + astRegBaseBox2( this, lbnd, ubnd ); + +/* Create a Box covering 1.0E-6 of this bounding box, centred on the + centre of the box. */ + if( astOK ) { + for( i = 0; i < nax; i++ ) { + if( ubnd[ i ] != DBL_MAX && lbnd[ i ] != -DBL_MAX ) { + hw = fabs( 0.5E-6*( ubnd[ i ] - lbnd[ i ] ) ); + c = 0.5*( ubnd[ i ] + lbnd[ i ] ); + if( hw == 0.0 ) hw = c*0.5E-6; + ubnd[ i ] = c + hw; + lbnd[ i ] = c - hw; + } else { + ubnd[ i ] = 0.0; + lbnd[ i ] = 0.0; + } + } + result = (AstRegion *) astBox( bfrm, 1, lbnd, ubnd, NULL, "", status ); + } + +/* Free resources. */ + lbnd = astFree( lbnd ); + ubnd = astFree( ubnd ); + bfrm = astAnnul( bfrm ); + +/* Return NULL if an error occurred. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the required pointer. */ + return result; +} + +static AstRegion *GetNegation( AstRegion *this, int *status ) { +/* +*+ +* Name: +* astGetNegation + +* Purpose: +* Obtain a pointer to a negated copy of the supplied Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstRegion *GetNegation( AstRegion *this, int *status ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a pointer to a Region which is a negated +* copy of "this". The copy is cached in the Region structure for +* future use. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* A pointer to the Region. This should be annulled (using astAnnul) +* when no longer needed. + +* Notes: +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* If the Region struture does not contain a pointer to a negated copy of + itself, create one now. */ + if( ! this->negation ) { + this->negation = astCopy( this ); + astNegate( this->negation ); + } + +/* Return a clone of the negation pointer. */ + return astClone( this->negation ); +} + +static AstFrameSet *GetRegFS( AstRegion *this, int *status ) { +/* +*+ +* Name: +* astGetRegFS + +* Purpose: +* Obtain a pointer to the FrameSet encapsulated within a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstFrameSet *astGetRegFS( AstRegion *this ) + +* Class Membership: +* Region virtual function + +* Description: +* This function returns a pointer to the FrameSet encapsulated by the +* Region. This is a clone, not a deep copy, of the pointer stored +* in the Region. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* A pointer to the FrameSet. + +* Notes: +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* Return the required pointer. */ + return astClone( this->frameset ); +} + +static AstPointSet *GetSubMesh( int *mask, AstPointSet *in, int *status ) { +/* +* Name: +* GetSubMesh + +* Purpose: +* Extract a selection of points from a PointSet. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstPointSet *GetSubMesh( int *mask, AstPointSet *in, int *status ) + +* Class Membership: +* Region member function + +* Description: +* This function creates a new PointSet holding points selected from a +* supplied PointSet. An integer mask is supplied to indicate which +* points should be selected. + +* Parameters: +* mask +* Pointer to a mask array, Its size should be equal to the number +* of points in the supplied PointSet. Each corresponding point will +* be copied if the mask value is zero. +* in +* Pointer to the PointSet holding the input positions. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* Pointer to the output PointSet. + +* Notes: +* - A null pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstPointSet *result; /* Pointer to output PointSet */ + double **ptr_in; /* Pointers to input axis values */ + double **ptr_out; /* Pointers to output axis values */ + double *pin; /* Pointer to next input axis value */ + double *pout; /* Pointer to next output axis value */ + int *m; /* Pointer to next mask element */ + int ic; /* Axis index */ + int ip; /* Point index */ + int nc; /* Number of axes in both PointSets */ + int npin; /* Number of points in input PointSet */ + int npout; /* Number of points in output PointSet */ + +/* Initialise. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Get the length of the mask. */ + npin = astGetNpoint( in ); + +/* Count the number of zeros in the mask. */ + npout = 0; + m = mask; + for( ip = 0; ip < npin; ip++ ) { + if( *(m++) == 0 ) npout++; + } + +/* Create the output PointSet and get pointers to its data arrays. */ + nc = astGetNcoord( in ); + result = astPointSet( npout, nc, "", status ); + ptr_in = astGetPoints( in ); + ptr_out = astGetPoints( result ); + +/* Check pointers can be dereferenced safely. */ + if( astOK ) { + +/* Copy the required axis values from the input to the output. */ + for( ic = 0; ic < nc; ic++ ) { + pin = ptr_in[ ic ]; + pout = ptr_out[ ic ]; + m = mask; + for( ip = 0; ip < npin; ip++, pin++, m++ ) { + if( *m == 0 ) *(pout++) = *pin; + } + } + } + +/* Return a pointer to the output PointSet. */ + return result; + +} + +static AstRegion *GetUnc( AstRegion *this, int def, int *status ){ +/* +*++ +* Name: +c astGetUnc +f AST_GETUNC + +* Purpose: +* Obtain uncertainty information from a Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c AstRegion *astGetUnc( AstRegion *this, int def ) +f RESULT = AST_GETUNC( THIS, DEF, STATUS ) + +* Class Membership: +* Region method. + +* Description: +* This function returns a Region which represents the uncertainty +* associated with positions within the supplied Region. See +c astSetUnc +f AST_SETUNC +* for more information about Region uncertainties and their use. + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +c def +f DEF = LOGICAL (Given) +* Controls what is returned if no uncertainty information has been +* associated explicitly with the supplied Region. If +c a non-zero value +f .TRUE. +* is supplied, then the default uncertainty Region used internally +* within AST is returned (see "Applicability" below). If +c zero is supplied, then NULL +f .FALSE. is supplied, then AST__NULL +* will be returned (without error). +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Returned Value: +c astGetUnc() +f AST_GETUNC = INTEGER +* A pointer to a Region describing the uncertainty in the supplied +* Region. + +* Applicability: +* CmpRegion +* The default uncertainty for a CmpRegion is taken from one of the +* two component Regions. If the first component Region has a +* non-default uncertainty, then it is used as the default uncertainty +* for the parent CmpRegion. Otherwise, if the second component Region +* has a non-default uncertainty, then it is used as the default +* uncertainty for the parent CmpRegion. If neither of the +* component Regions has non-default uncertainty, then the default +* uncertainty for the CmpRegion is 1.0E-6 of the bounding box of +* the CmpRegion. +* Prism +* The default uncertainty for a Prism is formed by combining the +* uncertainties from the two component Regions. If a component +* Region does not have a non-default uncertainty, then its default +* uncertainty will be used to form the default uncertainty of the +* parent Prism. +* Region +* For other classes of Region, the default uncertainty is 1.0E-6 +* of the bounding box of the Region. If the bounding box has zero +* width on any axis, then the uncertainty will be 1.0E-6 of the +* axis value. + +* Notes: +* - If uncertainty information is associated with a Region, and the +* coordinate system described by the Region is subsequently changed +* (e.g. by changing the value of its System attribute, or using the +c astMapRegion +f AST_MAPREGION +* function), then the uncertainty information returned by this function +* will be modified so that it refers to the coordinate system currently +* described by the supplied Region. +f - A null Object pointer (AST__NULL) will be returned if this +f function is invoked with STATUS set to an error value, or if it +c - A null Object pointer (NULL) will be returned if this +c function is invoked with the AST error status set, or if it +* should fail for any reason. + +*-- +*/ + +/* Local Variables: */ + AstRegion *result; /* Pointer to returned uncertainty Region */ + AstRegion *unc; /* Pointer to original uncertainty Region */ + +/* Initialise */ + result = NULL; + +/* Check inherited status */ + if( !astOK ) return result; + +/* Check that we have an uncertainty Region to return (either assigned or + default). */ + if( def || astTestUnc( this ) ) { + +/* Obtain the uncertainty Region and take a copy so that we can modify it + without affecting the supplied Region. */ + unc = astGetUncFrm( this, AST__CURRENT ); + result = astCopy( unc ); + unc = astAnnul( unc ); + +/* In its current context, the uncertainty region is known to refer to + the Frame of the supplied Region and so its RegionFS attribute will be + set to zero, indicating that the uncertainty FrameSet need not be + dumped. However, outside of AST this information cannot be implied, so + clear the RegionFS attribute so that the returned pointer will include + Frame information if it is dumped to a Channel. */ + astClearRegionFS( result ); + + } + +/* Return the result. */ + return result; + +} + +static AstRegion *GetUncFrm( AstRegion *this, int ifrm, int *status ) { +/* +*+ +* Name: +* astGetUncFrm + +* Purpose: +* Obtain a pointer to the uncertainty Region for a given Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstRegion *astGetUncFrm( AstRegion *this, int ifrm ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a pointer to a Region which represents the +* uncertainty associated with a position on the boundary of the given +* Region. The returned Region can refer to the either the base or +* the current Frame within the FrameSet encapsulated by the supplied +* Region as specified by the "ifrm" parameter. If the returned Region is +* re-centred at some point on the boundary of the supplied Region, then +* the re-centred Region will represent the region in which the true +* boundary position could be. + +* Parameters: +* this +* Pointer to the Region. +* ifrm +* The index of a Frame within the FrameSet encapsulated by "this". +* The returned Region will refer to the requested Frame. It should +* be either AST__CURRENT or AST__BASE. + +* Returned Value: +* A pointer to the Region. This should be annulled (using astAnnul) +* when no longer needed. + +* Notes: +* - A default uncertainty Region will be created if the supplied Region +* does not have an uncertainty Region. +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Local Variables: */ + AstFrame *frm; /* Current Frame from supplied Region */ + AstMapping *map; /* Supplied to uncertainty Mapping */ + AstRegion *result; /* Returned pointer */ + AstRegion *unc; /* Base frame uncertainty Region to use */ + +/* Initialise */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* If the Region has an explicitly assigned base-frame uncertainty Region, + use it. */ + if( this->unc ) { + unc = this->unc; + +/* If not, use the default base-frame uncertainty Region, creating it if + necessary. */ + } else { + if( !this->defunc ) this->defunc = astGetDefUnc( this ); + unc = this->defunc; + } + +/* If the uncertainty Region is the base Frame is required, just return a + clone of the uncertainty Region pointer. The Frame represented by an + uncertainty Region will always (barring bugs!) be the base Frame of + its parent Region. */ + if( ifrm == AST__BASE ) { + result = astClone( unc ); + +/* If the uncertainty Region is the current Frame is required... */ + } else { + +/* Get a Mapping from the Frame represented by the uncertainty Region + (the Region base Frame) to the Region current Frame. */ + map = astGetMapping( this->frameset, AST__BASE, AST__CURRENT ); + +/* If this is a UnitMap, the uncertainty Region is already in the correct + Frame, so just return the stored pointer. */ + if( astIsAUnitMap( map ) ) { + result = astClone( unc ); + +/* Otherwise, use this Mapping to map the uncertainty Region into the current + Frame. */ + } else { + frm = astGetFrame( this->frameset, AST__CURRENT ); + result = astMapRegion( unc, map, frm ); + +/* Free resources. */ + frm = astAnnul( frm ); + } + + map = astAnnul( map ); + } + +/* Return NULL if an error occurred. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the required pointer. */ + return result; +} + +static int GetUseDefs( AstObject *this_object, int *status ) { +/* +* Name: +* GetUseDefs + +* Purpose: +* Get the value of the UseDefs attribute for a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int GetUseDefs( AstObject *this_object, int *status ) { + +* Class Membership: +* Region member function (over-rides the protected astGetUseDefs +* method inherited from the Frame class). + +* Description: +* This function returns the value of the UseDefs attribute for a +* Region. supplying a suitable default. + +* Parameters: +* this +* Pointer to the Region. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* - The USeDefs value. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + int result; /* Value to return */ + +/* Initialise. */ + result = 0; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_object; + +/* If the UseDefs value for the Region has been set explicitly, use the + Get method inherited from the parent Frame class to get its value. */ + if( astTestUseDefs( this ) ) { + result = (*parent_getusedefs)( this_object, status ); + +/* Otherwise, supply a default value equal to the UseDefs value of the + encapsulated Frame. */ + } else { + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astGetUseDefs( fr ); + fr = astAnnul( fr ); + } + +/* Return the result. */ + return result; +} + +static int TestUnc( AstRegion *this, int *status ) { +/* +*+ +* Name: +* astTestUnc + +* Purpose: +* Does the Region contain non-default uncertainty information? + +* Type: +* Protected function. + +* Synopsis: +* int astTestUnc( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a flag indicating if the uncertainty Region in +* the supplied Region was supplied explicit (i.e. is not a default +* uncertainty Region). + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* Non-zero if the uncertainty Region was supplied explicitly. +* Zero otherwise. + +* Notes: +* - Classes of Region that encapsulate two or more other Regions +* inherit their default uncertainty from the encapsulated Regions. +* Non-default uncertainty in the component Regions does not imply +* that the parent Region has non-default uncertainty. +*- +*/ + +/* Check the global error status. */ + if ( !astOK ) return 0; + + return ( this->unc != NULL ); +} + +static AstFrame *RegFrame( AstRegion *this, int *status ) { +/* +*+ +* Name: +* astRegFrame + +* Purpose: +* Obtain a pointer to the current Frame for a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstFrame *astRegFrame( AstRegion *this ) + +* Class Membership: +* Region virtual function + +* Description: +* This function returns a pointer to the current Frame in the encapsulated +* FrameSet. This is a clone, not a deep copy, of the pointer stored +* in the FrameSet. For a deep copy, use astGetRegionFrame. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* A pointer to the Frame. + +* Notes: +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* Return the required pointer. */ + return astGetFrame( this->frameset, AST__CURRENT ); +} + +static AstMapping *RegMapping( AstRegion *this, int *status ) { +/* +*+ +* Name: +* astRegMapping + +* Purpose: +* Obtain a pointer to the simplified base->current Mapping for a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstMapping *astRegMapping( AstRegion *this ) + +* Class Membership: +* Region member function + +* Description: +* This function returns a pointer to the Mapping from the base to the +* current Frame int he encapsulated FrameSet. The returned Mapping is +* simplified before being returned. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* A pointer to the Mapping. + +* Notes: +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Local Variables: */ + AstMapping *map; /* Unsimplified Mapping */ + AstMapping *result; /* Simplified Mapping */ + +/* Initialise */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* If the "nomap" flag is set in the Region structure, re return a + UnitMap. */ + if( this->nomap ) { + result = (AstMapping *) astUnitMap( astGetNin( this->frameset ), "", status ); + +/* Otherwise use the Mapping from the Region's FrameSet. */ + } else { + +/* Get the Mapping */ + map = astGetMapping( this->frameset, AST__BASE, AST__CURRENT ); + +/* Simplify it. */ + result = astSimplify( map ); + +/* Annul the pointer to the unsimplified Mapping */ + map = astAnnul( map ); + } + +/* Return the required pointer. */ + return result; +} + +static int GetNaxes( AstFrame *this_frame, int *status ) { +/* +* Name: +* GetNaxes + +* Purpose: +* Determine how many axes a Region has. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int GetNaxes( AstFrame *this, int *status ) + +* Class Membership: +* Region member function (over-rides the astGetNaxes method +* inherited from the Frame class). + +* Description: +* This function returns the number of axes for a Region. This is equal +* to the number of axes in its current Frame. + +* Parameters: +* this +* Pointer to the Region. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The number of Region axes (zero or more). + +* Notes: +* - A value of zero will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + int result; /* Result to be returned */ + +/* Check the global error status. */ + if ( !astOK ) return 0; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's current Frame. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + +/* Obtain the number of axes in this Frame. */ + result = astGetNaxes( fr ); + +/* Annul the current Frame pointer. */ + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = 0; + +/* Return the result. */ + return result; +} + +static const int *GetPerm( AstFrame *this_frame, int *status ) { +/* +* Name: +* GetPerm + +* Purpose: +* Access the axis permutation array for the current Frame of a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* const int *GetPerm( AstFrame *this, int *status ) + +* Class Membership: +* Region member function (over-rides the astGetPerm protected +* method inherited from the Frame class). + +* Description: +* This function returns a pointer to the axis permutation array +* for the current Frame of a Region. This array constitutes a +* lookup-table that converts between an axis number supplied +* externally and the corresponding index in the Frame's internal +* axis arrays. + +* Parameters: +* this +* Pointer to the Region. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* Pointer to the current Frame's axis permutation array (a +* constant array of int). Each element of this contains the +* (zero-based) internal axis index to be used in place of the +* external index which is used to address the permutation +* array. If the current Frame has zero axes, this pointer will be +* NULL. + +* Notes: +* - The pointer returned by this function gives direct access to +* data internal to the Frame object. It remains valid only so long +* as the Frame exists. The permutation array contents may be +* modified by other functions which operate on the Frame and this +* may render the returned pointer invalid. +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to Region structure */ + const int *result; /* Result pointer value */ + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's current Frame and then obtain a + pointer to its axis permutation array. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astGetPerm( fr ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = NULL; + +/* Return the result. */ + return result; +} + +static AstFrame *GetRegionFrame( AstRegion *this, int *status ) { +/* +*++ +* Name: +c astGetRegionFrame +f AST_GETREGIONFRAME + +* Purpose: +* Obtain a pointer to the encapsulated Frame within a Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c AstFrame *astGetRegionFrame( AstRegion *this ) +f RESULT = AST_GETREGIONFRAME( THIS, STATUS ) + +* Class Membership: +* Region method. + +* Description: +* This function returns a pointer to the Frame represented by a +* Region. + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Returned Value: +c astGetRegionFrame() +f AST_GETREGIONFRAME = INTEGER +* A pointer to a deep copy of the Frame represented by the Region. +* Using this pointer to modify the Frame will have no effect on +* the Region. To modify the Region, use the Region pointer directly. + +* Notes: +* - A null Object pointer (AST__NULL) will be returned if this +c function is invoked with the AST error status set, or if it +f function is invoked with STATUS set to an error value, or if it +* should fail for any reason. +*-- +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstFrame *result; /* Pointer value to return */ + +/* Initialise. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Get a pointer to the current Frame of the encapsulated FrameSet. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + +/* Take a deep copy of it, and then annul the original pointer. */ + result = astCopy( fr ); + fr = astAnnul( fr ); + +/* If not OK, annul the returned pointer. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the result. */ + return result; +} + +static AstFrameSet *GetRegionFrameSet( AstRegion *this, int *status ) { +/* +*++ +* Name: +c astGetRegionFrameSet +f AST_GETREGIONFRAMESET + +* Purpose: +* Obtain a pointer to the encapsulated FrameSet within a Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c AstFrame *astGetRegionFrameSet( AstRegion *this ) +f RESULT = AST_GETREGIONFRAMESET( THIS, STATUS ) + +* Class Membership: +* Region method. + +* Description: +* This function returns a pointer to the FrameSet encapsulated by a +* Region. The base Frame is the Frame in which the box was originally +* defined, and the current Frame is the Frame into which the Region +* is currently mapped (i.e. it will be the same as the Frame returned +c by astGetRegionFrame). +f by AST_GETREGIONFRAME). + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Returned Value: +c astGetRegionFrameSet() +f AST_GETREGIONFRAMESET = INTEGER +* A pointer to a deep copy of the FrameSet represented by the Region. +* Using this pointer to modify the FrameSet will have no effect on +* the Region. + +* Notes: +* - A null Object pointer (AST__NULL) will be returned if this +c function is invoked with the AST error status set, or if it +f function is invoked with STATUS set to an error value, or if it +* should fail for any reason. +*-- +*/ + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* Return a deep copy of the encapsulated FrameSet. */ + return astCopy( this->frameset ); +} + +void astInitRegionVtab_( AstRegionVtab *vtab, const char *name, int *status ) { +/* +*+ +* Name: +* astInitRegionVtab + +* Purpose: +* Initialise a virtual function table for a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astInitRegionVtab( AstRegionVtab *vtab, const char *name ) + +* Class Membership: +* Region vtab initialiser. + +* Description: +* This function initialises the component of a virtual function +* table which is used by the Region class. + +* Parameters: +* vtab +* Pointer to the virtual function table. The components used by +* all ancestral classes will be initialised if they have not already +* been initialised. +* name +* Pointer to a constant null-terminated character string which contains +* the name of the class to which the virtual function table belongs (it +* is this pointer value that will subsequently be returned by the Object +* astClass function). +*- +*/ + +/* Local Variables: */ + astDECLARE_GLOBALS /* Pointer to thread-specific global data */ + AstFrameVtab *frame; /* Pointer to Frame component of Vtab */ + AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ + AstObjectVtab *object; /* Pointer to Object component of Vtab */ + +/* Check the local error status. */ + if ( !astOK ) return; + +/* Get a pointer to the thread specific global data structure. */ + astGET_GLOBALS(NULL); + +/* Initialize the component of the virtual function table used by the + parent class. */ + astInitFrameVtab( (AstFrameVtab *) vtab, name ); + +/* Store a unique "magic" value in the virtual function table. This + will be used (by astIsARegion) to determine if an object belongs + to this class. We can conveniently use the address of the (static) + class_check variable to generate this unique value. */ + vtab->id.check = &class_check; + vtab->id.parent = &(((AstFrameVtab *) vtab)->id); + +/* Initialise member function pointers. */ +/* ------------------------------------ */ + +/* Store pointers to the member functions (implemented here) that + provide virtual methods for this class. */ + vtab->ClearNegated = ClearNegated; + vtab->GetNegated = GetNegated; + vtab->SetNegated = SetNegated; + vtab->TestNegated = TestNegated; + + vtab->ClearRegionFS = ClearRegionFS; + vtab->GetRegionFS = GetRegionFS; + vtab->SetRegionFS = SetRegionFS; + vtab->TestRegionFS = TestRegionFS; + + vtab->ClearClosed = ClearClosed; + vtab->GetClosed = GetClosed; + vtab->SetClosed = SetClosed; + vtab->TestClosed = TestClosed; + + vtab->ClearMeshSize = ClearMeshSize; + vtab->GetMeshSize = GetMeshSize; + vtab->SetMeshSize = SetMeshSize; + vtab->TestMeshSize = TestMeshSize; + + vtab->ClearAdaptive = ClearAdaptive; + vtab->GetAdaptive = GetAdaptive; + vtab->SetAdaptive = SetAdaptive; + vtab->TestAdaptive = TestAdaptive; + + vtab->ClearFillFactor = ClearFillFactor; + vtab->GetFillFactor = GetFillFactor; + vtab->SetFillFactor = SetFillFactor; + vtab->TestFillFactor = TestFillFactor; + + vtab->ResetCache = ResetCache; + vtab->RegTrace = RegTrace; + vtab->GetBounded = GetBounded; + vtab->TestUnc = TestUnc; + vtab->ClearUnc = ClearUnc; + vtab->GetRegionFrame = GetRegionFrame; + vtab->GetRegionFrameSet = GetRegionFrameSet; + vtab->MapRegion = MapRegion; + vtab->Overlap = Overlap; + vtab->OverlapX = OverlapX; + vtab->Negate = Negate; + vtab->BndMesh = BndMesh; + vtab->BndBaseMesh = BndBaseMesh; + vtab->RegBaseGrid = RegBaseGrid; + vtab->RegBaseMesh = RegBaseMesh; + vtab->RegSplit = RegSplit; + vtab->RegBaseBox = RegBaseBox; + vtab->RegBaseBox2 = RegBaseBox2; + vtab->RegBasePick = RegBasePick; + vtab->RegCentre = RegCentre; + vtab->RegGrid = RegGrid; + vtab->RegMesh = RegMesh; + vtab->RegClearAttrib = RegClearAttrib; + vtab->RegSetAttrib = RegSetAttrib; + vtab->GetDefUnc = GetDefUnc; + vtab->GetNegation = GetNegation; + vtab->GetUncFrm = GetUncFrm; + vtab->SetUnc = SetUnc; + vtab->GetUnc = GetUnc; + vtab->ShowMesh = ShowMesh; + vtab->GetRegionBounds = GetRegionBounds; + vtab->GetRegionBounds2 = GetRegionBounds2; + vtab->GetRegionMesh = GetRegionMesh; + vtab->GetRegionPoints = GetRegionPoints; + vtab->RegOverlay = RegOverlay; + vtab->RegFrame = RegFrame; + vtab->RegDummyFS = RegDummyFS; + vtab->RegMapping = RegMapping; + vtab->RegPins = RegPins; + vtab->RegTransform = RegTransform; + vtab->BTransform = BTransform; + vtab->GetRegFS = GetRegFS; + vtab->SetRegFS = SetRegFS; + vtab->MaskB = MaskB; + vtab->MaskD = MaskD; + vtab->MaskF = MaskF; + vtab->MaskI = MaskI; + vtab->MaskL = MaskL; + vtab->MaskS = MaskS; + vtab->MaskUB = MaskUB; + vtab->MaskUI = MaskUI; + vtab->MaskUL = MaskUL; + vtab->MaskUS = MaskUS; +#if HAVE_LONG_DOUBLE /* Not normally implemented */ + vtab->MaskLD = MaskLD; +#endif + +/* Save the inherited pointers to methods that will be extended, and store + replacement pointers for methods which will be over-ridden by new member + functions implemented here. */ + object = (AstObjectVtab *) vtab; + mapping = (AstMappingVtab *) vtab; + frame = (AstFrameVtab *) vtab; + + parent_getobjsize = object->GetObjSize; + object->GetObjSize = GetObjSize; + + parent_getusedefs = object->GetUseDefs; + object->GetUseDefs = GetUseDefs; + +#if defined(THREAD_SAFE) + parent_managelock = object->ManageLock; + object->ManageLock = ManageLock; +#endif + + object->Cast = Cast; + object->Equal = Equal; + object->ClearAttrib = ClearAttrib; + object->GetAttrib = GetAttrib; + object->SetAttrib = SetAttrib; + object->TestAttrib = TestAttrib; + + mapping->ReportPoints = ReportPoints; + mapping->RemoveRegions = RemoveRegions; + mapping->Simplify = Simplify; + + frame->Abbrev = Abbrev; + frame->Angle = Angle; + frame->AxAngle = AxAngle; + frame->AxDistance = AxDistance; + frame->AxNorm = AxNorm; + frame->AxOffset = AxOffset; + frame->CheckPerm = CheckPerm; + frame->ClearDigits = ClearDigits; + frame->ClearDirection = ClearDirection; + frame->ClearDomain = ClearDomain; + frame->ClearFormat = ClearFormat; + frame->ClearLabel = ClearLabel; + frame->ClearMatchEnd = ClearMatchEnd; + frame->ClearMaxAxes = ClearMaxAxes; + frame->ClearMinAxes = ClearMinAxes; + frame->ClearPermute = ClearPermute; + frame->ClearPreserveAxes = ClearPreserveAxes; + frame->ClearSymbol = ClearSymbol; + frame->ClearTitle = ClearTitle; + frame->ClearUnit = ClearUnit; + frame->Convert = Convert; + frame->ConvertX = ConvertX; + frame->Distance = Distance; + frame->FindFrame = FindFrame; + frame->Format = Format; + frame->Centre = Centre; + frame->Gap = Gap; + frame->GetAxis = GetAxis; + frame->GetDigits = GetDigits; + frame->GetDirection = GetDirection; + frame->GetDomain = GetDomain; + frame->GetFormat = GetFormat; + frame->GetLabel = GetLabel; + frame->GetMatchEnd = GetMatchEnd; + frame->GetMaxAxes = GetMaxAxes; + frame->GetMinAxes = GetMinAxes; + frame->GetNaxes = GetNaxes; + frame->GetPerm = GetPerm; + frame->GetPermute = GetPermute; + frame->GetPreserveAxes = GetPreserveAxes; + frame->GetSymbol = GetSymbol; + frame->GetTitle = GetTitle; + frame->GetUnit = GetUnit; + frame->Intersect = Intersect; + frame->IsUnitFrame = IsUnitFrame; + frame->Match = Match; + frame->Norm = Norm; + frame->NormBox = NormBox; + frame->Offset = Offset; + frame->Offset2 = Offset2; + frame->Overlay = Overlay; + frame->PermAxes = PermAxes; + frame->PickAxes = PickAxes; + frame->Resolve = Resolve; + frame->ResolvePoints = ResolvePoints; + frame->SetAxis = SetAxis; + frame->SetDigits = SetDigits; + frame->SetDirection = SetDirection; + frame->SetDomain = SetDomain; + frame->SetFormat = SetFormat; + frame->SetLabel = SetLabel; + frame->SetMatchEnd = SetMatchEnd; + frame->SetMaxAxes = SetMaxAxes; + frame->SetMinAxes = SetMinAxes; + frame->SetPermute = SetPermute; + frame->SetPreserveAxes = SetPreserveAxes; + frame->SetSymbol = SetSymbol; + frame->SetTitle = SetTitle; + frame->SetUnit = SetUnit; + frame->SubFrame = SubFrame; + frame->SystemCode = SystemCode; + frame->SystemString = SystemString; + frame->TestDigits = TestDigits; + frame->TestDirection = TestDirection; + frame->TestDomain = TestDomain; + frame->TestFormat = TestFormat; + frame->TestLabel = TestLabel; + frame->TestMatchEnd = TestMatchEnd; + frame->TestMaxAxes = TestMaxAxes; + frame->TestMinAxes = TestMinAxes; + frame->TestPermute = TestPermute; + frame->TestPreserveAxes = TestPreserveAxes; + frame->TestSymbol = TestSymbol; + frame->TestTitle = TestTitle; + frame->TestUnit = TestUnit; + frame->Unformat = Unformat; + frame->ValidateAxis = ValidateAxis; + frame->ValidateAxisSelection = ValidateAxisSelection; + frame->ValidateSystem = ValidateSystem; + frame->LineDef = LineDef; + frame->LineContains = LineContains; + frame->LineCrossing = LineCrossing; + frame->LineOffset = LineOffset; + frame->MatchAxes = MatchAxes; + frame->MatchAxesX = MatchAxesX; + + frame->GetActiveUnit = GetActiveUnit; + frame->SetActiveUnit = SetActiveUnit; + frame->TestActiveUnit = TestActiveUnit; + + frame->GetTop = GetTop; + frame->SetTop = SetTop; + frame->TestTop = TestTop; + frame->ClearTop = ClearTop; + + frame->GetBottom = GetBottom; + frame->SetBottom = SetBottom; + frame->TestBottom = TestBottom; + frame->ClearBottom = ClearBottom; + + frame->GetEpoch = GetEpoch; + frame->SetEpoch = SetEpoch; + frame->TestEpoch = TestEpoch; + frame->ClearEpoch = ClearEpoch; + + frame->ClearObsAlt = ClearObsAlt; + frame->TestObsAlt = TestObsAlt; + frame->GetObsAlt = GetObsAlt; + frame->SetObsAlt = SetObsAlt; + + frame->ClearObsLat = ClearObsLat; + frame->TestObsLat = TestObsLat; + frame->GetObsLat = GetObsLat; + frame->SetObsLat = SetObsLat; + + frame->ClearObsLon = ClearObsLon; + frame->TestObsLon = TestObsLon; + frame->GetObsLon = GetObsLon; + frame->SetObsLon = SetObsLon; + + frame->GetSystem = GetSystem; + frame->SetSystem = SetSystem; + frame->TestSystem = TestSystem; + frame->ClearSystem = ClearSystem; + + frame->GetAlignSystem = GetAlignSystem; + frame->SetAlignSystem = SetAlignSystem; + frame->TestAlignSystem = TestAlignSystem; + frame->ClearAlignSystem = ClearAlignSystem; + +/* Declare the copy constructor, destructor and class dump + functions. */ + astSetDelete( vtab, Delete ); + astSetCopy( vtab, Copy ); + astSetDump( vtab, Dump, "Region", + "An area within a coordinate system" ); + +/* If we have just initialised the vtab for the current class, indicate + that the vtab is now initialised, and store a pointer to the class + identifier in the base "object" level of the vtab. */ + if( vtab == &class_vtab ) { + class_init = 1; + astSetVtabClassIdentifier( vtab, &(vtab->id) ); + } +} + +static void Intersect( AstFrame *this_frame, const double a1[2], + const double a2[2], const double b1[2], + const double b2[2], double cross[2], + int *status ) { +/* +* Name: +* Intersect + +* Purpose: +* Find the point of intersection between two geodesic curves. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void Intersect( AstFrame *this_frame, const double a1[2], +* const double a2[2], const double b1[2], +* const double b2[2], double cross[2], +* int *status ) + +* Class Membership: +* Region member function (over-rides the astIntersect method +* inherited from the Frame class). + +* Description: +* This function finds the coordinate values at the point of +* intersection between two geodesic curves. Each curve is specified +* by two points on the curve. + +* Parameters: +* this +* Pointer to the SkyFrame. +* a1 +* An array of double, with one element for each Frame axis. +* This should contain the coordinates of a point on the first +* geodesic curve. +* a2 +* An array of double, with one element for each Frame axis. +* This should contain the coordinates of a second point on the +* first geodesic curve. +* b1 +* An array of double, with one element for each Frame axis. +* This should contain the coordinates of a point on the second +* geodesic curve. +* b2 +* An array of double, with one element for each Frame axis. +* This should contain the coordinates of a second point on +* the second geodesic curve. +* cross +* An array of double, with one element for each Frame axis +* in which the coordinates of the required intersection +* point will be returned. These will be AST__BAD if the curves do +* not intersect. +* status +* Pointer to the inherited status variable. + +* Notes: +* - The geodesic curve used by this function is the path of +* shortest distance between two points, as defined by the +* astDistance function. +* - This function will return "bad" coordinate values (AST__BAD) +* if any of the input coordinates has this value. +* - For SkyFrames each curve will be a great circle, and in general +* each pair of curves will intersect at two diametrically opposite +* points on the sky. The returned position is the one which is +* closest to point "a1". +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke the + astIntersect method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astIntersect( fr, a1, a2, b1, b2, cross ); + fr = astAnnul( fr ); +} + +static int IsUnitFrame( AstFrame *this, int *status ){ +/* +* Name: +* IsUnitFrame + +* Purpose: +* Is this Frame equivalent to a UnitMap? + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int IsUnitFrame( AstFrame *this, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astIsUnitFrame +* method inherited from the Frame class). + +* Description: +* This function returns a flag indicating if the supplied Frame is +* equivalent to a UnitMap when treated as a Mapping (note, the Frame +* class inherits from Mapping and therefore every Frame is also a Mapping). + +* Parameters: +* this +* Pointer to the Frame. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A non-zero value is returned if the supplied Frame is equivalent to +* a UnitMap when treated as a Mapping. + +*- +*/ + +/* Check the global error status. */ + if( !astOK ) return 0; + +/* The Region class is never equivalent to a UnitMap. */ + return 0; +} + +static int LineContains( AstFrame *this_frame, AstLineDef *l, int def, double *point, int *status ) { +/* +* Name: +* LineContains + +* Purpose: +* Determine if a line contains a point. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int LineContains( AstFrame *this, AstLineDef *l, int def, double *point, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astLineContains +* method inherited from the Frame class). + +* Description: +* This function determines if the supplied point is on the supplied +* line within the supplied Frame. The start point of the line is +* considered to be within the line, but the end point is not. The tests +* are that the point of closest approach of the line to the point should +* be between the start and end, and that the distance from the point to +* the point of closest aproach should be less than 1.0E-7 of the length +* of the line. + +* Parameters: +* this +* Pointer to the Frame. +* l +* Pointer to the structure defining the line. +* def +* Should be set non-zero if the "point" array was created by a +* call to astLineCrossing (in which case it may contain extra +* information following the axis values),and zero otherwise. +* point +* Point to an array containing the axis values of the point to be +* tested, possibly followed by extra cached information (see "def"). +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A non-zero value is returned if the line contains the point. + +* Notes: +* - The pointer supplied for "l" should have been created using the +* astLineDef method. These structures contained cached information about +* the lines which improve the efficiency of this method when many +* repeated calls are made. An error will be reported if the structure +* does not refer to the Frame specified by "this". +* - Zero will be returned if this function is invoked with the global +* error status set, or if it should fail for any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + int result; /* Returned value */ + +/* Initialise */ + result =0; + +/* Obtain a pointer to the Region's current Frame and then invoke the + method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( ((AstRegion *) this_frame)->frameset, AST__CURRENT ); + result = astLineContains( fr, l, def, point ); + fr = astAnnul( fr ); + +/* Return the result. */ + return result; +} + +static int LineCrossing( AstFrame *this_frame, AstLineDef *l1, AstLineDef *l2, + double **cross, int *status ) { +/* +* Name: +* LineCrossing + +* Purpose: +* Determine if two lines cross. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int LineCrossing( AstFrame *this, AstLineDef *l1, AstLineDef *l2, +* double **cross, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astLineCrossing +* method inherited from the Frame class). + +* Description: +* This function determines if the two suplied line segments cross, +* and if so returns the axis values at the point where they cross. +* A flag is also returned indicating if the crossing point occurs +* within the length of both line segments, or outside one or both of +* the line segments. + +* Parameters: +* this +* Pointer to the Frame. +* l1 +* Pointer to the structure defining the first line. +* l2 +* Pointer to the structure defining the second line. +* cross +* Pointer to a location at which to put a pointer to a dynamically +* alocated array containing the axis values at the crossing. If +* NULL is supplied no such array is returned. Otherwise, the returned +* array should be freed using astFree when no longer needed. If the +* lines are parallel (i.e. do not cross) then AST__BAD is returned for +* all axis values. Note usable axis values are returned even if the +* lines cross outside the segment defined by the start and end points +* of the lines. The order of axes in the returned array will take +* account of the current axis permutation array if appropriate. Note, +* sub-classes such as SkyFrame may append extra values to the end +* of the basic frame axis values. A NULL pointer is returned if an +* error occurs. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A non-zero value is returned if the lines cross at a point which is +* within the [start,end) segment of both lines. If the crossing point +* is outside this segment on either line, or if the lines are parallel, +* zero is returned. Note, the start point is considered to be inside +* the length of the segment, but the end point is outside. + +* Notes: +* - The pointers supplied for "l1" and "l2" should have been created +* using the astLineDef method. These structures contained cached +* information about the lines which improve the efficiency of this method +* when many repeated calls are made. An error will be reported if +* either structure does not refer to the Frame specified by "this". +* - Zero will be returned if this function is invoked with the global +* error status set, or if it should fail for any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + int result; /* Returned value */ + +/* Initialise */ + result =0; + +/* Obtain a pointer to the Region's current Frame and then invoke the + method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( ((AstRegion *) this_frame)->frameset, AST__CURRENT ); + result = astLineCrossing( fr, l1, l2, cross ); + fr = astAnnul( fr ); + +/* Return the result. */ + return result; +} + +static AstLineDef *LineDef( AstFrame *this_frame, const double start[2], + const double end[2], int *status ) { +/* +* Name: +* LineDef + +* Purpose: +* Creates a structure describing a line segment in a 2D Frame. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstLineDef *LineDef( AstFrame *this, const double start[2], +* const double end[2], int *status ) + +* Class Membership: +* Region member function (over-rides the protected astLineDef +* method inherited from the Frame class). + +* Description: +* This function creates a structure containing information describing a +* given line segment within the supplied 2D Frame. This may include +* information which allows other methods such as astLineCrossing to +* function more efficiently. Thus the returned structure acts as a +* cache to store intermediate values used by these other methods. + +* Parameters: +* this +* Pointer to the Frame. Must have 2 axes. +* start +* An array of 2 doubles marking the start of the line segment. +* end +* An array of 2 doubles marking the end of the line segment. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* Pointer to the memory structure containing the description of the +* line. This structure should be freed using astFree when no longer +* needed. A NULL pointer is returned (without error) if any of the +* supplied axis values are AST__BAD. + +* Notes: +* - A null pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstLineDef *result; /* Returned value */ + +/* Initialise */ + result = NULL; + +/* Obtain a pointer to the Region's current Frame and then invoke the + method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( ((AstRegion *) this_frame)->frameset, AST__CURRENT ); + result = astLineDef( fr, start, end ); + fr = astAnnul( fr ); + +/* Return the result. */ + return result; +} + +static void LineOffset( AstFrame *this_frame, AstLineDef *line, double par, + double prp, double point[2], int *status ){ +/* +* Name: +* LineOffset + +* Purpose: +* Find a position close to a line. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void LineOffset( AstFrame *this, AstLineDef *line, double par, +* double prp, double point[2], int *status ) + +* Class Membership: +* Region member function (over-rides the protected astLineOffset +* method inherited from the Frame class). + +* Description: +* This function returns a position formed by moving a given distance along +* the supplied line, and then a given distance away from the supplied line. + +* Parameters: +* this +* Pointer to the Frame. +* line +* Pointer to the structure defining the line. +* par +* The distance to move along the line from the start towards the end. +* prp +* The distance to move at right angles to the line. Positive +* values result in movement to the left of the line, as seen from +* the observer, when moving from start towards the end. +* status +* Pointer to the inherited status variable. + +* Notes: +* - The pointer supplied for "line" should have been created using the +* astLineDef method. This structure contains cached information about the +* line which improves the efficiency of this method when many repeated +* calls are made. An error will be reported if the structure does not +* refer to the Frame specified by "this". +*/ + + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + +/* Obtain a pointer to the Region's current Frame and then invoke the + method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( ((AstRegion *) this_frame)->frameset, AST__CURRENT ); + astLineOffset( fr, line, par, prp, point ); + fr = astAnnul( fr ); +} + + +#if defined(THREAD_SAFE) +static int ManageLock( AstObject *this_object, int mode, int extra, + AstObject **fail, int *status ) { +/* +* Name: +* ManageLock + +* Purpose: +* Manage the thread lock on an Object. + +* Type: +* Private function. + +* Synopsis: +* #include "object.h" +* AstObject *ManageLock( AstObject *this, int mode, int extra, +* AstObject **fail, int *status ) + +* Class Membership: +* Region member function (over-rides the astManageLock protected +* method inherited from the parent class). + +* Description: +* This function manages the thread lock on the supplied Object. The +* lock can be locked, unlocked or checked by this function as +* deteremined by parameter "mode". See astLock for details of the way +* these locks are used. + +* Parameters: +* this +* Pointer to the Object. +* mode +* An integer flag indicating what the function should do: +* +* AST__LOCK: Lock the Object for exclusive use by the calling +* thread. The "extra" value indicates what should be done if the +* Object is already locked (wait or report an error - see astLock). +* +* AST__UNLOCK: Unlock the Object for use by other threads. +* +* AST__CHECKLOCK: Check that the object is locked for use by the +* calling thread (report an error if not). +* extra +* Extra mode-specific information. +* fail +* If a non-zero function value is returned, a pointer to the +* Object that caused the failure is returned at "*fail". This may +* be "this" or it may be an Object contained within "this". Note, +* the Object's reference count is not incremented, and so the +* returned pointer should not be annulled. A NULL pointer is +* returned if this function returns a value of zero. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A local status value: +* 0 - Success +* 1 - Could not lock or unlock the object because it was already +* locked by another thread. +* 2 - Failed to lock a POSIX mutex +* 3 - Failed to unlock a POSIX mutex +* 4 - Bad "mode" value supplied. + +* Notes: +* - This function attempts to execute even if an error has already +* occurred. +*/ + +/* Local Variables: */ + AstRegion *this; /* Pointer to Region structure */ + int result; /* Returned status value */ + +/* Initialise */ + result = 0; + +/* Check the supplied pointer is not NULL. */ + if( !this_object ) return result; + +/* Obtain a pointers to the Region structure. */ + this = (AstRegion *) this_object; + +/* Invoke the ManageLock method inherited from the parent class. */ + if( !result ) result = (*parent_managelock)( this_object, mode, extra, + fail, status ); + +/* Invoke the astManageLock method on any Objects contained within + the supplied Object. */ + if( !result ) result = astManageLock( this->frameset, mode, extra, fail ); + if( !result ) result = astManageLock( this->points, mode, extra, fail ); + if( !result ) result = astManageLock( this->unc, mode, extra, fail ); + if( !result ) result = astManageLock( this->negation, mode, extra, fail ); + if( !result ) result = astManageLock( this->defunc, mode, extra, fail ); + if( !result ) result = astManageLock( this->basemesh, mode, extra, fail ); + if( !result ) result = astManageLock( this->basegrid, mode, extra, fail ); + + return result; + +} +#endif + +static AstRegion *MapRegion( AstRegion *this, AstMapping *map0, + AstFrame *frame0, int *status ) { +/* +*+ +* Name: +* astMapRegion + +* Purpose: +* Transform a Region into a new Frame using a given Mapping. + +* Type: +* Protected virtual function. + +* Synopsis: +* #include "region.h" +* AstRegion *astMapRegion( AstRegion *this, AstMapping *map, +* AstFrame *frame ) + +* Class Membership: +* Region method. + +* Description: +* This function returns a pointer to a new Region which corresponds to +* supplied Region in some other specified coordinate system. A +* Mapping is supplied which transforms positions between the old and new +* coordinate systems. The new Region may not be of the same class as +* the original region. + +* Parameters: +* this +* Pointer to the Region. +* map +* Pointer to a Mapping which transforms positions from the +* coordinate system represented by the supplied Region to the +* coordinate system specified by "frame". The supplied Mapping should +* define both forward and inverse transformations, and these +* transformations should form a genuine inverse pair. That is, +* transforming a position using the forward transformation and then +* using the inverse transformation should produce the original input +* position. Some Mapping classes (such as PermMap, MathMap, SphMap) +* can result in Mappings for which this is not true. +* frame +* Pointer to a Frame describing the coordinate system in which +* the new Region is required. + +* Returned Value: +* astMapRegion() +* A pointer to a new Region. This Region will represent the area +* within the coordinate system specified by "frame" which corresponds +* to the supplied Region. + +* Notes: +* - This is the protected implementation of this function - it does +* not simplify the returned Region. The public implementation is +* astMapRegionID, which simplifies the returned Region. +* - A null Object pointer (AST__NULL) will be returned if this +* function is invoked with the AST error status set, or if it +* should fail for any reason. +*- +*/ + +/* Local Variables: */ + AstFrame *frame; + AstFrameSet *fs; + AstMapping *tmap; + AstMapping *usemap; + AstMapping *map; + AstPointSet *ps1; + AstPointSet *pst; + AstPointSet *ps2; + AstRegion *usethis; + AstRegion *result; + double **ptr1; + double **ptr2; + int *axflags; + int *inax; + int *keep; + int *outax; + int i; + int icurr; + int j; + int nax1; + int nkept; + int nnew; + int nold; + int np; + int ntotal; + int ok; + +/* Initialise returned value. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Initialise local variables */ + axflags = NULL; + +/* If a FrameSet was supplied for the Mapping, use the base->current + Mapping */ + if( astIsAFrameSet( map0 ) ) { + map = astGetMapping( (AstFrameSet *) map0, AST__BASE, AST__CURRENT ); + } else { + map = astClone( map0 ); + } + +/* If a FrameSet was supplied for the Frame, use the current Frame. */ + if( astIsAFrameSet( frame0 ) ) { + frame = astGetFrame( (AstFrameSet *) frame0, AST__CURRENT ); + } else { + frame = astClone( frame0 ); + } + +/* First check the Mapping is suitable. It must defined both a forward + and an inverse Mapping. */ + if( !astGetTranInverse( map ) ) { + astError( AST__NODEF, "astMapRegion(%s): The supplied %s does not " + "define an inverse transformation.", status, astGetClass( this ), + astGetClass( map ) ); + } else if( !astGetTranForward( map ) ) { + astError( AST__NODEF, "astMapRegion(%s): The supplied %s does not " + "define a forward transformation.", status, astGetClass( this ), + astGetClass( map ) ); + } + + +/* Get the number of axes in the supplied Region. */ + nold = astGetNaxes( this ); + +/* Get the number of axes in the returned Region. */ + nnew = astGetNaxes( frame ); + +/* The forward transformation must not introduce any bad axis values. We + can only perform this test reliably if the supplied Region has no bad + axis values. */ + ps1 = this->points; + if( ps1 ) { + nax1 = astGetNcoord( ps1 ); + np = astGetNpoint( ps1 ); + ptr1 = astGetPoints( ps1 ); + if( ptr1 ) { + +/* Check the axis values defining the Region are good. */ + ok = 1; + for( i = 0; i < nax1 && ok; i++ ){ + for( j = 0; j < np; j++ ) { + if( ptr1[ i ][ j ] == AST__BAD ){ + ok = 0; + break; + } + } + } + if( ok ) { + +/* Transform the points defining the supplied Region into the current Frame + of the Region. */ + pst = astRegTransform( this, ps1, 1, NULL, NULL ); + +/* The use the supplied Mapping to transfom them into the new Frame. */ + ps2 = astTransform( map, pst, 1, NULL ); + +/* Test if any of these axis values are bad. */ + ptr2 = astGetPoints( ps2 ); + if( ptr2 ) { + for( i = 0; i < nnew && ok; i++ ){ + for( j = 0; j < np; j++ ) { + if( ptr2[ i ][ j ] == AST__BAD ){ + ok = 0; + break; + } + } + } + if( !ok ) { + astError( AST__NODEF, "astMapRegion(%s): The region which " + "results from using the supplied %s to transform " + "the supplied %s is undefined.", status, astGetClass( this ), + astGetClass( map ), astGetClass( this ) ); + +/* If all axis values are good, use the inverse transformation of the + supplied Mapping to transform them back to the Frame of the supplied + Region. */ + } else { + pst = astAnnul( pst ); + pst = astTransform( map, ps2, 0, NULL ); + +/* Get a flag for each input of the supplied Mapping (i.e. each axis of + the supplied Region) which is non-zero if the inverse transformation + of the Mapping has produced any good axis values. */ + ptr1 = astGetPoints( pst ); + axflags = astCalloc( nold, sizeof(int) ); + if( astOK ) { + for( i = 0; i < nold; i++ ){ + for( j = 0; j < np; j++ ) { + if( ptr1[ i ][ j ] != AST__BAD ){ + axflags[ i ] = 1; + break; + } + } + } + } + } + } + ps2 = astAnnul( ps2 ); + pst = astAnnul( pst ); + } + } + } + +/* Assume we will be using the supplied Region (this) and Mapping (map). */ + usethis = astClone( this ); + usemap = astClone( map ); + +/* If the new Frame for the Region has fewer axes than the old Frame, see + if we can discard some base-frame axes. We only do this if the inverse + transformation would otherwise supply bad values for the unused axes. + Using bad axis values is not a good idea as some operations cannot be + performed if any bad values are supplied. Also having more axes than + needed is bad as it results in fewer mesh points per axis. */ + if( nnew < nold ) { + +/* First invert the Mapping since astMapSplit only allows selection of + inputs, and we want to select outputs. */ + astInvert( map ); + +/* Create an array holding the indices of the required inputs. */ + inax = astMalloc( nnew*sizeof(int) ); + if( astOK ) for( i = 0; i < nnew; i++ ) inax[i] = i; + +/* Attempt to split the mapping to extract a new mapping that omits any + unnecessary outputs (i.e. outputs that are indepenent of the selected + inputs). Check the Mapping was split successfully. */ + outax = astMapSplit( map, nnew, inax, &tmap ); + if( outax ) { + +/* Get the number of old axes that have been retained in the Mapping. */ + nkept = astGetNout( tmap ); + +/* Now we need to ensure that any unused axes for which the Mapping + creates non-bad values are retained (such values are significant + since they may determine whether the new Region is null or not). + We only need to do this if any of the outputs that were split off + above have been found to generate good values, as indicated by the + "axflags" array. Count the number of extra axes that need to be kept, + over and above those that are kept by the Mapping returned by + astMapSplit above. */ + ntotal = 0; + keep = NULL; + if( axflags ) { + keep = astMalloc( nold*sizeof(int) ); + if( astOK ) { + +/* Loop round each axis in the supplied Region. */ + for( i = 0; i < nold; i++ ) { + +/* Search the "outax" array to see if this axis was retained by astMapSplit. + If it was, append its index to the total list of axes to keep. */ + ok = 0; + for( j = 0; j < nkept; j++ ) { + if( outax[ j ] == i ) { + keep[ ntotal++ ] = i; + ok = 1; + break; + } + } + +/* If the axis was not retained by astMapSplit, but generates good axis + values, also append its index to the total list of axes to keep. */ + if( !ok && axflags[ i ] ) { + keep[ ntotal++ ] = i; + } + } + } + } + +/* If there are no extra axes to keep, then the Mapping returned by + astMapSplit above can be used as it is. */ + if( ntotal == nkept ) { + +/* The values in the "outax" array will hold the zero-based indices of + the original old axes that are retained by the new Mapping. We need to + create a copy of the supplied Region that includes only these axes. */ + usethis = astAnnul( usethis ); + usethis = astPickAxes( this, nkept, outax, NULL ); + +/* Use the temportary Mapping returned by astMapSplit in place of the + supplied Mapping (remember to invert to undo the inversion performed + above). */ + usemap = astAnnul( usemap ); + usemap = astClone( tmap ); + astInvert( usemap ); + +/* Free temporary resources. */ + tmap = astAnnul( tmap ); + outax = astFree( outax ); + +/* If we need to retain some extra axes because they generate good values + (even though they are independent of the new Frame axes)... */ + } else if( ntotal > nkept ){ + +/* We know the old Frame axes that we want to keep, so use astMapSplit + in the opposite direction - i.e. use it on the Mapping form old to + new. */ + astInvert( map ); + + tmap = astAnnul( tmap ); + outax = astFree( outax ); + + outax = astMapSplit( map, ntotal, keep, &tmap ); + if( outax ) { + + usethis = astAnnul( usethis ); + usethis = astPickAxes( this, ntotal, keep, NULL ); + + usemap = astAnnul( usemap ); + usemap = astClone( tmap ); + + tmap = astAnnul( tmap ); + outax = astFree( outax ); + + } + + astInvert( map ); + } + keep = astFree( keep ); + } + inax = astFree( inax ); + +/* Invert the Mapping again to bring it back to its original state. */ + astInvert( map ); + } + +/* Take a deep copy of the supplied Region. */ + result = astCopy( usethis ); + +/* Get a pointer to the encapsulated FrameSet. */ + if( astOK ) { + fs = result->frameset; + +/* Add in the new Frame and Mapping. First note the index of the original + current Frame. */ + icurr = astGetCurrent( fs ); + astAddFrame( fs, AST__CURRENT, usemap, frame ); + +/* Remove the original current Frame. */ + astRemoveFrame( fs, icurr ); + +/* The base and current Frames of the resulting FrameSet are now (in + general) different and so the Region should include its FrameSet in any + Dump. */ + astSetRegionFS( result, 1 ); + } + +/* Since the Mapping has been changed, any cached information calculated + on the basis of the Mapping properties may no longer be up to date. */ + astResetCache( result ); + +/* Free resources */ + usemap = astAnnul( usemap ); + usethis = astAnnul( usethis ); + map = astAnnul( map ); + frame = astAnnul( frame ); + axflags = astFree( axflags ); + +/* If not OK, annul the returned pointer. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the result. */ + return result; +} + +/* +*++ +* Name: +c astMask<X> +f AST_MASK<X> + +* Purpose: +* Mask a region of a data grid. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c int astMask<X>( AstRegion *this, AstMapping *map, int inside, int ndim, +c const int lbnd[], const int ubnd[], <Xtype> in[], +c <Xtype> val ) +f RESULT = AST_MASK<X>( THIS, MAP, INSIDE, NDIM, LBND, UBND, IN, VAL, +f STATUS ) + +* Class Membership: +* Mapping method. + +* Description: +* This is a set of functions for masking out regions within gridded data +* (e.g. an image). The functions modifies a given data grid by +* assigning a specified value to all samples which are inside (or outside +c if "inside" is zero) +f if INSIDE is .FALSE.) +* the specified Region. +* +* You should use a masking function which matches the numerical +* type of the data you are processing by replacing <X> in +c the generic function name astMask<X> by an appropriate 1- or +f the generic function name AST_MASK<X> by an appropriate 1- or +* 2-character type code. For example, if you are masking data +c with type "float", you should use the function astMaskF (see +f with type REAL, you should use the function AST_MASKR (see +* the "Data Type Codes" section below for the codes appropriate to +* other numerical types). + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to a Region. +c map +f MAP = INTEGER (Given) +* Pointer to a Mapping. The forward transformation should map +* positions in the coordinate system of the supplied Region +* into pixel coordinates as defined by the +c "lbnd" and "ubnd" parameters. A NULL pointer +f LBND and UBND arguments. A value of AST__NULL +* can be supplied if the coordinate system of the supplied Region +* corresponds to pixel coordinates. This is equivalent to +* supplying a UnitMap. +* +* The number of inputs for this Mapping (as given by its Nin attribute) +* should match the number of axes in the supplied Region (as given +* by the Naxes attribute of the Region). +* The number of outputs for the Mapping (as given by its Nout attribute) +* should match the number of +c grid dimensions given by the value of "ndim" +f grid dimensions given by the value of NDIM +* below. +c inside +f INSIDE = INTEGER (Given) +* A boolean value which indicates which pixel are to be masked. If +c a non-zero value +f .TRUE. +* is supplied, then all grid pixels with centres inside the supplied +* Region are assigned the value given by +c "val", +f VAL, +* and all other pixels are left unchanged. If +c zero +f .FALSE. +* is supplied, then all grid pixels with centres not inside the supplied +* Region are assigned the value given by +c "val", +f VAL, +* and all other pixels are left unchanged. Note, the Negated +* attribute of the Region is used to determine which pixel are +* inside the Region and which are outside. So the inside of a Region +* which has not been negated is the same as the outside of the +* corresponding negated Region. +* +* For types of Region such as PointList which have zero volume, +* pixel centres will rarely fall exactly within the Region. For +* this reason, the inclusion criterion is changed for zero-volume +* Regions so that pixels are included (or excluded) if any part of +* the Region passes through the pixel. For a PointList, this means +* that pixels are included (or excluded) if they contain at least +* one of the points listed in the PointList. +c ndim +f NDIM = INTEGER (Given) +* The number of dimensions in the input grid. This should be at +* least one. +c lbnd +f LBND( NDIM ) = INTEGER (Given) +c Pointer to an array of integers, with "ndim" elements, +f An array +* containing the coordinates of the centre of the first pixel +* in the input grid along each dimension. +c ubnd +f UBND( NDIM ) = INTEGER (Given) +c Pointer to an array of integers, with "ndim" elements, +f An array +* containing the coordinates of the centre of the last pixel in +* the input grid along each dimension. +* +c Note that "lbnd" and "ubnd" together define the shape +f Note that LBND and UBND together define the shape +* and size of the input grid, its extent along a particular +c (j'th) dimension being ubnd[j]-lbnd[j]+1 (assuming the +c index "j" to be zero-based). They also define +f (J'th) dimension being UBND(J)-LBND(J)+1. They also define +* the input grid's coordinate system, each pixel having unit +* extent along each dimension with integral coordinate values +* at its centre. +c in +f IN( * ) = <Xtype> (Given and Returned) +c Pointer to an array, with one element for each pixel in the +f An array, with one element for each pixel in the +* input grid, containing the data to be masked. The +* numerical type of this array should match the 1- or +* 2-character type code appended to the function name (e.g. if +c you are using astMaskF, the type of each array element +c should be "float"). +f you are using AST_MASKR, the type of each array element +f should be REAL). +* +* The storage order of data within this array should be such +* that the index of the first grid dimension varies most +* rapidly and that of the final dimension least rapidly +c (i.e. Fortran array indexing is used). +f (i.e. normal Fortran array storage order). +* +* On exit, the samples specified by +c "inside" are set to the value of "val". +f INSIDE are set to the value of VAL. +* All other samples are left unchanged. +c val +f VAL = <Xtype> (Given) +* This argument should have the same type as the elements of +c the "in" array. It specifies the value used to flag the +f the IN array. It specifies the value used to flag the +* masked data (see +c "inside"). +f INSIDE). +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Returned Value: +c astMask<X>() +f AST_MASK<X> = INTEGER +* The number of pixels to which a value of +c "badval" +f BADVAL +* has been assigned. + +* Notes: +* - A value of zero will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +* - An error will be reported if the overlap of the Region and +* the array cannot be determined. + +* Data Type Codes: +* To select the appropriate masking function, you should +c replace <X> in the generic function name astMask<X> with a +f replace <X> in the generic function name AST_MASK<X> with a +* 1- or 2-character data type code, so as to match the numerical +* type <Xtype> of the data you are processing, as follows: +c - D: double +c - F: float +c - L: long int +c - UL: unsigned long int +c - I: int +c - UI: unsigned int +c - S: short int +c - US: unsigned short int +c - B: byte (signed char) +c - UB: unsigned byte (unsigned char) +f - D: DOUBLE PRECISION +f - R: REAL +f - I: INTEGER +f - UI: INTEGER (treated as unsigned) +f - S: INTEGER*2 (short integer) +f - US: INTEGER*2 (short integer, treated as unsigned) +f - B: BYTE (treated as signed) +f - UB: BYTE (treated as unsigned) +* +c For example, astMaskD would be used to process "double" +c data, while astMaskS would be used to process "short int" +c data, etc. +f For example, AST_MASKD would be used to process DOUBLE +f PRECISION data, while AST_MASKS would be used to process +f short integer data (stored in an INTEGER*2 array), etc. +f +f For compatibility with other Starlink facilities, the codes W +f and UW are provided as synonyms for S and US respectively (but +f only in the Fortran interface to AST). + +*-- +*/ +/* Define a macro to implement the function for a specific data + type. */ +#define MAKE_MASK(X,Xtype) \ +static int Mask##X( AstRegion *this, AstMapping *map, int inside, int ndim, \ + const int lbnd[], const int ubnd[], \ + Xtype in[], Xtype val, int *status ) { \ +\ +/* Local Variables: */ \ + AstFrame *grid_frame; /* Pointer to Frame describing grid coords */ \ + AstRegion *used_region; /* Pointer to Region to be used by astResample */ \ + Xtype *c; /* Pointer to next array element */ \ + Xtype *d; /* Pointer to next array element */ \ + Xtype *out; /* Pointer to the array used for resample output */ \ + Xtype *tmp_out; /* Pointer to temporary output array */ \ + double *lbndgd; /* Pointer to array holding lower grid bounds */ \ + double *ubndgd; /* Pointer to array holding upper grid bounds */ \ + int *lbndg; /* Pointer to array holding lower grid bounds */ \ + int *ubndg; /* Pointer to array holding upper grid bounds */ \ + int idim; /* Loop counter for coordinate dimensions */ \ + int ipix; /* Loop counter for pixel index */ \ + int nax; /* Number of Region axes */ \ + int nin; /* Number of Mapping input coordinates */ \ + int nout; /* Number of Mapping output coordinates */ \ + int npix; /* Number of pixels in supplied array */ \ + int npixg; /* Number of pixels in bounding box */ \ + int result; /* Result value to return */ \ +\ +/* Initialise. */ \ + result = 0; \ +\ +/* Check the global error status. */ \ + if ( !astOK ) return result; \ +\ +/* Obtain value for the Naxes attribute of the Region. */ \ + nax = astGetNaxes( this ); \ +\ +/* If supplied, obtain values for the Nin and Nout attributes of the Mapping. */ \ + if( map ) { \ + nin = astGetNin( map ); \ + nout = astGetNout( map ); \ +\ +/* If OK, check that the number of mapping inputs matches the \ + number of axes in the Region. Report an error if necessary. */ \ + if ( astOK && ( nax != nin ) ) { \ + astError( AST__NGDIN, "astMask"#X"(%s): Bad number of mapping " \ + "inputs (%d).", status, astGetClass( this ), nin ); \ + astError( AST__NGDIN, "The %s given requires %d coordinate value%s " \ + "to specify a position.", status, \ + astGetClass( this ), nax, ( nax == 1 ) ? "" : "s" ); \ + } \ +\ +/* If OK, check that the number of mapping outputs matches the \ + number of grid dimensions. Report an error if necessary. */ \ + if ( astOK && ( ndim != nout ) ) { \ + astError( AST__NGDIN, "astMask"#X"(%s): Bad number of mapping " \ + "outputs (%d).", status, astGetClass( this ), nout ); \ + astError( AST__NGDIN, "The pixel grid requires %d coordinate value%s " \ + "to specify a position.", status, \ + ndim, ( ndim == 1 ) ? "" : "s" ); \ + } \ +\ +/* Create a new Region by mapping the supplied Region with the supplied \ + Mapping. The resulting Region represents a region in grid coordinates. */ \ + grid_frame = astFrame( ndim, "Domain=grid", status ); \ + used_region = astMapRegion( this, map, grid_frame ); \ + grid_frame = astAnnul( grid_frame ); \ +\ +/* If no Mapping was supplied check that the number of grid dimensions \ + matches the number of axes in the Region.*/ \ + } else if ( astOK && ( ( ndim != nax ) || ( ndim < 1 ) ) ) { \ + used_region = NULL; \ + astError( AST__NGDIN, "astMask"#X"(%s): Bad number of input grid " \ + "dimensions (%d).", status, astGetClass( this ), ndim ); \ + if ( ndim != nax ) { \ + astError( AST__NGDIN, "The %s given requires %d coordinate value%s " \ + "to specify an input position.", status, \ + astGetClass( this ), nax, ( nax == 1 ) ? "" : "s" ); \ + } \ +\ +/* If no Mapping was supplied and the parameters look OK, clone the \ + supplied Region pointer for use later on. */ \ + } else { \ + used_region = astClone( this ); \ + } \ +\ +/* Check that the lower and upper bounds of the input grid are \ + consistent. Report an error if any pair is not. */ \ + if ( astOK ) { \ + for ( idim = 0; idim < ndim; idim++ ) { \ + if ( lbnd[ idim ] > ubnd[ idim ] ) { \ + astError( AST__GBDIN, "astMask"#X"(%s): Lower bound of " \ + "input grid (%d) exceeds corresponding upper bound " \ + "(%d).", status, astGetClass( this ), \ + lbnd[ idim ], ubnd[ idim ] ); \ + astError( AST__GBDIN, "Error in input dimension %d.", status, \ + idim + 1 ); \ + break; \ + } \ + } \ + } \ +\ +/* Allocate memory, and then get the bounding box of this new Region in its \ + current Frame (grid coordinates). This bounding box assumes the region \ + has not been negated. */ \ + lbndg = astMalloc( sizeof( int )*(size_t) ndim ); \ + ubndg = astMalloc( sizeof( int )*(size_t) ndim ); \ + lbndgd = astMalloc( sizeof( double )*(size_t) ndim ); \ + ubndgd = astMalloc( sizeof( double )*(size_t) ndim ); \ + if( astOK ) { \ + astGetRegionBounds( used_region, lbndgd, ubndgd ); \ +\ +/* We convert the floating point bounds to integer pixel bounds, and at \ + the same time expand the box by 2 pixels at each edge to ensure that \ + rounding errors etc do not cause any of the Region to fall outside (or \ + on) the box. Do not let the expanded box extend outside the supplied \ + array bounds. Also note the total number of pixels in the supplied \ + array, and in the bounding box. */ \ + npix = 1; \ + npixg = 1; \ + for ( idim = 0; idim < ndim; idim++ ) { \ + if( lbndgd[ idim ] != AST__BAD && ubndgd[ idim ] != AST__BAD ) { \ + lbndg[ idim ] = astMAX( lbnd[ idim ], (int)( lbndgd[ idim ] + 0.5 ) - 2 ); \ + ubndg[ idim ] = astMIN( ubnd[ idim ], (int)( ubndgd[ idim ] + 0.5 ) + 2 ); \ + } else { \ + lbndg[ idim ] = lbnd[ idim ]; \ + ubndg[ idim ] = ubnd[ idim ]; \ + } \ + npix *= ( ubnd[ idim ] - lbnd[ idim ] + 1 ); \ + if( npixg >= 0 ) npixg *= ( ubndg[ idim ] - lbndg[ idim ] + 1 ); \ + } \ +\ +/* If the bounding box is null, fill the mask with the supplied value if \ + we assigning the value to the outside of the region (do the opposite if \ + the Region has been negated). */ \ + if( npixg <= 0 && astOK ) { \ + if( ( inside != 0 ) == ( astGetNegated( used_region ) != 0 ) ) { \ + c = in; \ + for( ipix = 0; ipix < npix; ipix++ ) *(c++) = val; \ + result = npix; \ + } \ +\ +/* If the bounding box is null, return without action. */ \ + } else if( npixg > 0 && astOK ) { \ +\ +/* All points outside this box are either all inside, or all outside, the \ + Region. So we can speed up processing by setting all the points which are \ + outside the box to the supplied data value (if required). This is \ + faster than checking each point individually using the Transform method \ + of the Region. We do this by supplying an alternative output array to \ + the resampling function below, which has been pre-filled with "val" at \ + every pixel. */ \ + if( ( inside != 0 ) == ( astGetNegated( used_region ) != 0 ) ) { \ +\ +/* Allocate memory for the alternative output array, and fill it with \ + "val". */ \ + tmp_out = astMalloc( sizeof( Xtype )*(size_t) npix ); \ + if( tmp_out ) { \ + c = tmp_out; \ + for( ipix = 0; ipix < npix; ipix++ ) *(c++) = val; \ + result = npix - npixg; \ + } \ +\ +/* Indicate that we will use this temporary array rather than the \ + supplied array. */ \ + out = tmp_out; \ +\ +/* If the outside of the grid box is outside the region of interest it \ + will be unchanged in the resturned array. Therefore we can use the \ + supplied array as the output array below. */ \ + } else { \ + tmp_out = NULL; \ + out = in; \ + } \ +\ +/* Temporarily invert the Region if required. The Region Transform methods \ + leave interior points unchanged and assign AST__BAD to exterior points. \ + This is the opposite of what we want (which is to leave exterior \ + points unchanged and assign VAL to interior points), so we negate the \ + region if the inside is to be assigned the value VAL.*/ \ + if( inside ) astNegate( used_region ); \ +\ +/* Invoke astResample to mask just the region inside the bounding box found \ + above (specified by lbndg and ubndg), since all the points outside this \ + box will already contain their required value. */ \ + result += astResample##X( used_region, ndim, lbnd, ubnd, in, NULL, AST__NEAREST, \ + NULL, NULL, 0, 0.0, 100, val, ndim, \ + lbnd, ubnd, lbndg, ubndg, out, NULL ); \ +\ +/* Revert to the original setting of the Negated attribute. */ \ + if( inside ) astNegate( used_region ); \ +\ +/* If required, copy the output data from the temporary output array to \ + the supplied array, and then free the temporary output array. */ \ + if( tmp_out ) { \ + c = tmp_out; \ + d = in; \ + for( ipix = 0; ipix < npix; ipix++ ) *(d++) = *(c++); \ + tmp_out = astFree( tmp_out ); \ + }\ + }\ + } \ +\ +/* Free resources */ \ + ubndg = astFree( ubndg ); \ + lbndg = astFree( lbndg ); \ + ubndgd = astFree( ubndgd ); \ + lbndgd = astFree( lbndgd ); \ + used_region = astAnnul( used_region ); \ +\ +/* If an error occurred, clear the returned result. */ \ + if ( !astOK ) result = 0; \ +\ +/* Return the result. */ \ + return result; \ +} + +/* Expand the above macro to generate a function for each required + data type. */ +#if HAVE_LONG_DOUBLE /* Not normally implemented */ +MAKE_MASK(LD,long double) +#endif +MAKE_MASK(D,double) +MAKE_MASK(L,long int) +MAKE_MASK(UL,unsigned long int) +MAKE_MASK(I,int) +MAKE_MASK(UI,unsigned int) +MAKE_MASK(S,short int) +MAKE_MASK(US,unsigned short int) +MAKE_MASK(B,signed char) +MAKE_MASK(UB,unsigned char) +MAKE_MASK(F,float) + +/* Undefine the macro. */ +#undef MAKE_MASK + + + +static int Match( AstFrame *this_frame, AstFrame *target, int matchsub, + int **template_axes, int **target_axes, + AstMapping **map, AstFrame **result, int *status ) { +/* +* Name: +* Match + +* Purpose: +* Determine if conversion is possible between two coordinate systems. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int Match( AstFrame *template, AstFrame *target, int matchsub, +* int **template_axes, int **target_axes, +* AstMapping **map, AstFrame **result, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astMatch +* method inherited from the Frame class). + +* Description: +* This function matches the current Frame of a "template" Region +* to a "target" frame and determines whether it is possible to +* convert coordinates between them. If it is, a Mapping that +* performs the transformation is returned along with a new Frame +* that describes the coordinate system that results when this +* Mapping is applied to the current Frame of the target +* Region. In addition, information is returned to allow the axes +* in this "result" Frame to be associated with the corresponding +* axes in the target and template Frames from which they are +* derived. + +* Parameters: +* template +* Pointer to the template Region, whose current Frame +* describes the coordinate system (or set of possible +* coordinate systems) into which we wish to convert our +* coordinates. +* target +* Pointer to the target Frame. This describes the coordinate +* system in which we already have coordinates. +* matchsub +* If zero then a match only occurs if the template is of the same +* class as the target, or of a more specialised class. If non-zero +* then a match can occur even if this is not the case. +* template_axes +* Address of a location where a pointer to int will be returned +* if the requested coordinate conversion is possible. This +* pointer will point at a dynamically allocated array of +* integers with one element for each axis of the "result" Frame +* (see below). It must be freed by the caller (using astFree) +* when no longer required. +* +* For each axis in the result Frame, the corresponding element +* of this array will return the index of the axis in the +* template Region's current Frame from which it is +* derived. If it is not derived from any template Region +* axis, a value of -1 will be returned instead. +* target_axes +* Address of a location where a pointer to int will be returned +* if the requested coordinate conversion is possible. This +* pointer will point at a dynamically allocated array of +* integers with one element for each axis of the "result" Frame +* (see below). It must be freed by the caller (using astFree) +* when no longer required. +* +* For each axis in the result Frame, the corresponding element +* of this array will return the index of the target Frame axis +* from which it is derived. If it is not derived from any +* target Frame axis, a value of -1 will be returned instead. +* map +* Address of a location where a pointer to a new Mapping will +* be returned if the requested coordinate conversion is +* possible. If returned, the forward transformation of this +* Mapping may be used to convert coordinates between the target +* Frame and the result Frame (see below) and the inverse +* transformation will convert in the opposite direction. +* result +* Address of a location where a pointer to a new Frame will be +* returned if the requested coordinate conversion is +* possible. If returned, this Frame describes the coordinate +* system that results from applying the returned Mapping +* (above) to the "target" coordinate system. In general, this +* Frame will combine attributes from (and will therefore be +* more specific than) both the target Frame and the current +* Frame of the template Region. In particular, when the +* template allows the possibility of transformaing to any one +* of a set of alternative coordinate systems, the "result" +* Frame will indicate which of the alternatives was used. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A non-zero value is returned if the requested coordinate +* conversion is possible. Otherwise zero is returned (this will +* not in itself result in an error condition). + +* Notes: +* - A value of zero will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to Region's current Frame */ + int match; /* Result to be returned */ + +/* Initialise the returned values. */ + *template_axes = NULL; + *target_axes = NULL; + *map = NULL; + *result = NULL; + match = 0; + +/* Check the global error status. */ + if ( !astOK ) return match; + +/* Invoke the parent astMatch method on the current Frame within the + encapsulated FrameSet within the Region. */ + fr = astGetFrame( ((AstRegion *) this_frame)->frameset, AST__CURRENT ); + match = astMatch( fr, target, matchsub, template_axes, target_axes, map, result ); + fr = astAnnul( fr ); + +/* Return the result. */ + return match; +} + +static void MatchAxes( AstFrame *frm1_frame, AstFrame *frm2, int *axes, + int *status ) { +/* +* Name: +* MatchAxes + +* Purpose: +* Find any corresponding axes in two Frames. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void MatchAxes( AstFrame *frm1, AstFrame *frm2, int *axes ) +* int *status ) + +* Class Membership: +* Region member function (over-rides the protected astMatchAxes +* method inherited from the Frame class). + +* Description: +* This function looks for corresponding axes within two supplied +* Frames. An array of integers is returned that contains an element +* for each axis in the second supplied Frame. An element in this array +* will be set to zero if the associated axis within the second Frame +* has no corresponding axis within the first Frame. Otherwise, it +* will be set to the index (a non-zero positive integer) of the +* corresponding axis within the first supplied Frame. + +* Parameters: +* frm1 +* Pointer to the first Frame. +* frm2 +* Pointer to the second Frame. +* axes +* Pointer to an +* integer array in which to return the indices of the axes (within +* the second Frame) that correspond to each axis within the first +* Frame. Axis indices start at 1. A value of zero will be stored +* in the returned array for each axis in the first Frame that has +* no corresponding axis in the second Frame. +* +* The number of elements in this array must be greater than or +* equal to the number of axes in the first Frame. +* status +* Pointer to inherited status value. + +* Notes: +* - Corresponding axes are identified by the fact that a Mapping +* can be found between them using astFindFrame or astConvert. Thus, +* "corresponding axes" are not necessarily identical. For instance, +* SkyFrame axes in two Frames will match even if they describe +* different celestial coordinate systems +*/ + +/* Local Variables: */ + AstFrame *frm1; /* Pointer to Region's current Frame */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Invoke the astMatchAxesX method on frm2, passing it the current Frame + within the encapsulated FrameSet within the Region as "frm1". */ + frm1 = astGetFrame( ((AstRegion *) frm1_frame)->frameset, AST__CURRENT ); + astMatchAxesX( frm2, frm1, axes ); + frm1 = astAnnul( frm1 ); +} + +static void MatchAxesX( AstFrame *frm2_frame, AstFrame *frm1, int *axes, + int *status ) { +/* +* Name: +* MatchAxesX + +* Purpose: +* Find any corresponding axes in two Frames. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void MatchAxesX( AstFrame *frm2, AstFrame *frm1, int *axes ) +* int *status ) + +* Class Membership: +* Region member function (over-rides the protected astMatchAxesX +* method inherited from the Frame class). + +* This function looks for corresponding axes within two supplied +* Frames. An array of integers is returned that contains an element +* for each axis in the second supplied Frame. An element in this array +* will be set to zero if the associated axis within the second Frame +* has no corresponding axis within the first Frame. Otherwise, it +* will be set to the index (a non-zero positive integer) of the +* corresponding axis within the first supplied Frame. + +* Parameters: +* frm2 +* Pointer to the second Frame. +* frm1 +* Pointer to the first Frame. +* axes +* Pointer to an integer array in which to return the indices of +* the axes (within the first Frame) that correspond to each axis +* within the second Frame. Axis indices start at 1. A value of zero +* will be stored in the returned array for each axis in the second +* Frame that has no corresponding axis in the first Frame. +* +* The number of elements in this array must be greater than or +* equal to the number of axes in the second Frame. +* status +* Pointer to inherited status value. + +* Notes: +* - Corresponding axes are identified by the fact that a Mapping +* can be found between them using astFindFrame or astConvert. Thus, +* "corresponding axes" are not necessarily identical. For instance, +* SkyFrame axes in two Frames will match even if they describe +* different celestial coordinate systems +*/ + +/* Local Variables: */ + AstFrame *frm2; + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Get a pointer to the current Frame in the FrameSet. */ + frm2 = astGetFrame( ((AstRegion *) frm2_frame)->frameset, AST__CURRENT ); + +/* Invoke the astMatchAxesX on the current Frame. */ + astMatchAxesX( frm2, frm1, axes ); + +/* Free resources */ + frm2 = astAnnul( frm2 ); +} + +static void Negate( AstRegion *this, int *status ) { +/* +*++ +* Name: +c astNegate +f AST_NEGATE + +* Purpose: +* Negate the area represented by a Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c void astNegate( AstRegion *this ) +f CALL AST_NEGATE( THIS, STATUS ) + +* Class Membership: +* Region method. + +* Description: +* This function negates the area represented by a Region. That is, +* points which were previously inside the region will then be +* outside, and points which were outside will be inside. This is +* acomplished by toggling the state of the Negated attribute for +* the supplied region. + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +f STATUS = INTEGER (Given and Returned) +f The global status. + +*-- +*/ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Toggle the Negated attribute. */ + astSetNegated( this, astGetNegated( this ) ? 0 : 1 ); + +} + +static void Norm( AstFrame *this_frame, double value[], int *status ) { +/* +* Name: +* Norm + +* Purpose: +* Normalise a set of Region coordinates. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void Norm( AstAxis *this, double value[], int *status ) + +* Class Membership: +* Region member function (over-rides the astNorm method +* inherited from the Frame class). + +* Description: +* This function converts a set of coordinate values for the +* current Frame of a Region, which might potentially be +* unsuitable for display to a user (for instance, may lie outside +* the expected range of values) into a set of acceptable +* alternative values suitable for display. +* +* Typically, for Frames whose axes represent cyclic values (such +* as angles or positions on the sky), this function wraps an +* arbitrary set of coordinates, so that they lie within the first +* cycle (say zero to 2*pi or -pi/2 to +pi/2). For Frames with +* ordinary linear axes, without constraints, this function will +* typically return the original coordinate values unchanged. + +* Parameters: +* this +* Pointer to the Region. +* value +* An array of double, with one element for each Region axis. +* This should contain the initial set of coordinate values, +* which will be modified in place. +* status +* Pointer to the inherited status variable. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to the current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's current Frame and invoke this + Frame's astNorm method to obtain the new values. Annul the Frame + pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astNorm( fr, value ); + fr = astAnnul( fr ); +} + +static void NormBox( AstFrame *this_frame, double lbnd[], double ubnd[], + AstMapping *reg, int *status ) { +/* +* Name: +* NormBox + +* Purpose: +* Extend a box to include effect of any singularities in the Frame. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void astNormBox( AstFrame *this, double lbnd[], double ubnd[], +* AstMapping *reg, int *status ) + +* Class Membership: +* Region member function (over-rides the astNormBox method inherited +* from the Frame class). + +* Description: +* This function modifies a supplied box to include the effect of any +* singularities in the co-ordinate system represented by the Frame. +* For a normal Cartesian coordinate system, the box will be returned +* unchanged. Other classes of Frame may do other things. For instance, +* a SkyFrame will check to see if the box contains either the north +* or south pole and extend the box appropriately. + +* Parameters: +* this +* Pointer to the Frame. +* lbnd +* An array of double, with one element for each Frame axis +* (Naxes attribute). Initially, this should contain a set of +* lower axis bounds for the box. They will be modified on exit +* to include the effect of any singularities within the box. +* ubnd +* An array of double, with one element for each Frame axis +* (Naxes attribute). Initially, this should contain a set of +* upper axis bounds for the box. They will be modified on exit +* to include the effect of any singularities within the box. +* reg +* A Mapping which should be used to test if any singular points are +* inside or outside the box. The Mapping should leave an input +* position unchanged if the point is inside the box, and should +* set all bad if the point is outside the box. +* status +* Pointer to the inherited status variable. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to the current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's current Frame and invoke this + Frame's astNormBox method to obtain the new values. Annul the Frame + pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astNormBox( fr, lbnd, ubnd, reg ); + fr = astAnnul( fr ); +} + +static void Offset( AstFrame *this_frame, const double point1[], + const double point2[], double offset, double point3[], int *status ) { +/* +* Name: +* Offset + +* Purpose: +* Calculate an offset along a geodesic curve. + +* Type: +* Public virtual function. + +* Synopsis: +* #include "region.h" +* void Offset( AstFrame *this, +* const double point1[], const double point2[], +* double offset, double point3[], int *status ) + +* Class Membership: +* Region member function (over-rides the protected astOffset +* method inherited from the Frame class). + +* Description: +* This function finds the Region coordinate values of a point +* which is offset a specified distance along the geodesic curve +* between two other points. + +* Parameters: +* this +* Pointer to the Region. +* point1 +* An array of double, with one element for each Region axis. +* This should contain the coordinates of the point marking the +* start of the geodesic curve. +* point2 +* An array of double, with one element for each Region axis +* This should contain the coordinates of the point marking the +* end of the geodesic curve. +* offset +* The required offset from the first point along the geodesic +* curve. If this is positive, it will be towards the second +* point. If it is negative, it will be in the opposite +* direction. This offset need not imply a position lying +* between the two points given, as the curve will be +* extrapolated if necessary. +* point3 +* An array of double, with one element for each Region axis +* in which the coordinates of the required point will be +* returned. +* status +* Pointer to the inherited status variable. + +* Notes: +* - The geodesic curve used by this function is the path of +* shortest distance between two points, as defined by the +* astDistance function. +* - This function will return "bad" coordinate values (AST__BAD) +* if any of the input coordinates has this value. +* - "Bad" coordinate values will also be returned if the two +* points supplied are coincident (or otherwise fail to uniquely +* specify a geodesic curve) but the requested offset is non-zero. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's current Frame and invoke this + Frame's astOffset method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astOffset( fr, point1, point2, offset, point3 ); + fr = astAnnul( fr ); +} + +static double Offset2( AstFrame *this_frame, const double point1[2], + double angle, double offset, double point2[2], int *status ){ +/* +* Name: +* Offset2 + +* Purpose: +* Calculate an offset along a geodesic curve in a 2D Frame. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* double Offset2( AstFrame *this, const double point1[2], double angle, +* double offset, double point2[2], int *status ); + +* Class Membership: +* Region member function (over-rides the protected astOffset2 +* method inherited from the Frame class). + +* Description: +* This function finds the Frame coordinate values of a point which +* is offset a specified distance along the geodesic curve at a +* given angle from a specified starting point. It can only be +* used with 2-dimensional Frames. +* +* For example, in a basic Frame, this offset will be along the +* straight line joining two points. For a more specialised Frame +* describing a sky coordinate system, however, it would be along +* the great circle passing through two sky positions. + +* Parameters: +* this +* Pointer to the Frame. +* point1 +* An array of double, with one element for each Frame axis +* (Naxes attribute). This should contain the coordinates of the +* point marking the start of the geodesic curve. +* angle +* The angle (in radians) from the positive direction of the second +* axis, to the direction of the required position, as seen from +* the starting position. Positive rotation is in the sense of +* rotation from the positive direction of axis 2 to the positive +* direction of axis 1. +* offset +* The required offset from the first point along the geodesic +* curve. If this is positive, it will be in the direction of the +* given angle. If it is negative, it will be in the opposite +* direction. +* point2 +* An array of double, with one element for each Frame axis +* in which the coordinates of the required point will be returned. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The direction of the geodesic curve at the end point. That is, the +* angle (in radians) between the positive direction of the second +* axis and the continuation of the geodesic curve at the requested +* end point. Positive rotation is in the sense of rotation from +* the positive direction of axis 2 to the positive direction of axis 1. + +* Notes: +* - The geodesic curve used by this function is the path of +* shortest distance between two points, as defined by the +* astDistance function. +* - An error will be reported if the Frame is not 2-dimensional. +* - This function will return "bad" coordinate values (AST__BAD) +* if any of the input coordinates has this value. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double result; /* Value to return */ + +/* Check the global error status. */ + if ( !astOK ) return AST__BAD; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke the + astOffset2 method for this Frame. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astOffset2( fr, point1, angle, offset, point2 ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = AST__BAD; + +/* Return the result. */ + return result; +} + +static int Overlap( AstRegion *this, AstRegion *that, int *status ){ +/* +*++ +* Name: +c astOverlap +f AST_OVERLAP + +* Purpose: +* Test if two regions overlap each other. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c int astOverlap( AstRegion *this, AstRegion *that ) +f RESULT = AST_OVERLAP( THIS, THAT, STATUS ) + +* Class Membership: +* Region method. + +* Description: +* This function returns an integer value indicating if the two +* supplied Regions overlap. The two Regions are converted to a commnon +* coordinate system before performing the check. If this conversion is +* not possible (for instance because the two Regions represent areas in +* different domains), then the check cannot be performed and a zero value +* is returned to indicate this. + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the first Region. +c that +f THAT = INTEGER (Given) +* Pointer to the second Region. +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Returned Value: +c astOverlap() +f AST_OVERLAP = INTEGER +* A value indicating if there is any overlap between the two Regions. +* Possible values are: +* +* 0 - The check could not be performed because the second Region +* could not be mapped into the coordinate system of the first +* Region. +* +* 1 - There is no overlap between the two Regions. +* +* 2 - The first Region is completely inside the second Region. +* +* 3 - The second Region is completely inside the first Region. +* +* 4 - There is partial overlap between the two Regions. +* +* 5 - The Regions are identical to within their uncertainties. +* +* 6 - The second Region is the exact negation of the first Region +* to within their uncertainties. + +* Notes: +* - The returned values 5 and 6 do not check the value of the Closed +* attribute in the two Regions. +* - A value of zero will be returned if this function is invoked with the +* AST error status set, or if it should fail for any reason. +*-- + +* Implementation Notes: +* This function is simply a wrap-up for the protected astOverlapX +* method which performs the required processing but swaps the order +* of the two arguments. This is a trick to allow the astOverlap method +* to be over-ridden by derived classes on the basis of the class of either +* of the two arguments. +*/ + +/* Check the global error status. */ + if ( !astOK ) return 0; + +/* Invoke the "astOverlapX" method with the two arguments swapped. */ + return astOverlapX( that, this ); +} + +static int OverlapX( AstRegion *that, AstRegion *this, int *status ){ +/* +*+ +* Name: +* astOverlapX + +* Purpose: +* Test if two regions overlap each other. + +* Type: +* Protected virtual function. + +* Synopsis: +* #include "region.h" +* int astOverlapX( AstRegion *that, AstRegion *this ) + +* Class Membership: +* Region method. + +* Description: +* This function performs the processing for the public astOverlap +* method and has exactly the same interface except that the order +* of the two arguments is swapped. This is a trick to allow +* the astOverlap method to be over-ridden by derived classes on +* the basis of the class of either of its two arguments. +* +* See the astOverlap method for details of the interface. +*- +*/ + +/* Local Variables: */ + AstFrame *bfrm_reg1; /* Pointer to base Frame in "reg1" Frame */ + AstFrame *frm_reg1; /* Pointer to current Frame in "reg1" Frame */ + AstFrameSet *fs0; /* FrameSet connecting Region Frames */ + AstFrameSet *fs; /* FrameSet connecting Region Frames */ + AstMapping *cmap; /* Mapping connecting Region Frames */ + AstMapping *map; /* Mapping form "reg2" current to "reg1" base */ + AstMapping *map_reg1; /* Pointer to current->base Mapping in "reg1" */ + AstPointSet *ps1; /* Mesh covering second Region */ + AstPointSet *ps3; /* Mesh covering first Region */ + AstPointSet *ps4; /* Mesh covering first Region */ + AstPointSet *ps2; /* Mesh covering second Region */ + AstPointSet *reg2_mesh; /* Mesh covering second Region */ + AstPointSet *reg1_mesh; /* Mesh covering first Region */ + AstPointSet *reg2_submesh; /* Second Region mesh minus boundary points */ + AstRegion *reg1; /* Region to use as the first Region */ + AstRegion *reg2; /* Region to use as the second Region */ + AstRegion *unc1; /* "unc" mapped into Frame of first Region */ + AstRegion *unc; /* Uncertainty in second Region */ + double **ptr1; /* Pointer to mesh axis values */ + double **ptr; /* Pointer to pointset data */ + double *p; /* Pointer to next axis value */ + int *mask; /* Mask identifying common boundary points */ + int allbad; /* Were all axis values bad? */ + int allgood; /* Were all axis values good? */ + int bnd1; /* Does reg1 have a finite boundary */ + int bnd2; /* Does reg2 have a finite boundary */ + int bnd_that; /* Does "that" have a finite boundary */ + int bnd_this; /* Does "this" have a finite boundary */ + int case1; /* First region inside second region? */ + int first; /* First pass? */ + int good; /* Any good axis values found? */ + int i; /* Mesh axis index */ + int iax; /* Axis index */ + int inv0; /* Original FrameSet Invert flag */ + int ip; /* Index of point */ + int j; /* Mesh point index */ + int nc; /* Number of axis values per point */ + int np; /* Number of points in mesh */ + int result; /* Value to return */ + int reg1_neg; /* Was "reg1" negated to make it bounded? */ + int reg2_neg; /* Was "reg2" negated to make it bounded? */ + int that_neg; /* Was "that" negated to make it bounded? */ + int this_neg; /* Was "this" negated to make it bounded? */ + int touch; /* Do the Regions touch? */ + +/* Initialise. */ + result = 0; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Return 5 if the two Regions are equal using the astEqual method. */ + if( astEqual( this, that ) ) { + return 5; + +/* Return 6 if the two Regions are equal using the Equal method after + temporarily negating the first. */ + } else { + astNegate( this ); + result = astEqual( this, that ); + astNegate( this ); + if( result ) return 6; + } + +/* Get a FrameSet which connects the Frame represented by the second Region + to the Frame represented by the first Region. Check that the conection is + defined. */ + fs0 = astConvert( that, this, "" ); + if( !fs0 ) return 0; + inv0 = astGetInvert( fs0 ); + +/* The rest of this function tests for overlap by representing one of the + Regions as a mesh of points along its boundary, and then checking to see + if any of the points in this mesh fall inside or outside the other Region. + This can only be done if the Region has a boundary of finite length (e.g. + Circles, Boxes, etc). Other Regions (e.g. some Intervals) do not have + finite boundaries and consequently report an error if an attempt is made + to represent them using a boundary mesh. We now therefore check to see if + either of the two Regions has a finite boundary length. This will be the + case if the region is bounded, or if it can be made bounded simply by + negating it. If a Region is unbounded regardless of the setting of its + Negated flag, then it does not have a finite boundary. We leave the + Negated attributes (temporaily) set to the values that cause the + Regions to be bounded. Set flags to indicate if the Regions have been + negated. */ + bnd_this = astGetBounded( this ); + if( !bnd_this ) { + astNegate( this ); + bnd_this = astGetBounded( this ); + if( ! bnd_this ) { + astNegate( this ); + this_neg = 0; + } else { + this_neg = 1; + } + } else { + this_neg = 0; + } + + bnd_that = astGetBounded( that ); + if( !bnd_that ) { + astNegate( that ); + bnd_that = astGetBounded( that ); + if( ! bnd_that ) { + astNegate( that ); + that_neg = 0; + } else { + that_neg = 1; + } + } else { + that_neg = 0; + } + +/* If neither Regions has a finite boundary, then we cannot currently + determine any overlap, so report an error. Given more time, it + is probably possible to think of some way of determining overlap + between two unbounded Regions, but it will probably not be a common + requirement and so is currently put off to a rainy day. */ + if( !bnd_this && !bnd_that && astOK ) { + astError( AST__INTER, "astOverlap(Region): Neither of the two " + "supplied Regions (classes %s and %s) has a finite " + "boundary.", status, astGetClass(this), astGetClass(that) ); + astError( AST__INTER, "The current implementation of astOverlap " + "cannot determine the overlap between two Regions " + "unless at least one of them has a finite boundary." , status); + } + +/* If only one of the two Regions has a finite boundary, we must use its + mesh first. Choose the finite boundary Region as the "second" region. + Also store a flag indicating if the first Region has a finite boundary. */ + if( bnd_that ) { + reg1 = this; + reg2 = that; + bnd1 = bnd_this; + bnd2 = bnd_that; + reg1_neg = this_neg; + reg2_neg = that_neg; + } else { + reg1 = that; + reg2 = this; + bnd1 = bnd_that; + bnd2 = bnd_this; + reg1_neg = that_neg; + reg2_neg = this_neg; + } + +/* We may need to try again with the above selections swapped. We only do + this once though. Set a flag to indicate that we are about to start the + first pass. */ + first = 1; +L1: + +/* Get a FrameSet which connects the Frame represented by the second Region + to the Frame represented by the first Region. Check that the conection is + defined. */ + fs = astClone( fs0 ); + astSetInvert( fs, (reg2 == that ) ? inv0 : 1 - inv0 ); + if( fs ) { + +/* Get a pointer to the Frame represented by the first Region. */ + frm_reg1 = astGetFrame( reg1->frameset, AST__CURRENT ); + +/* Get a pointer to the Mapping from current to base Frame in the first + Region. */ + map_reg1 = astGetMapping( reg1->frameset, AST__CURRENT, AST__BASE ); + +/* Get the Mapping from the current Frame of the second Region to the + current Frame of the first Region. */ + cmap = astGetMapping( fs, AST__BASE, AST__CURRENT ); + +/* Combine these Mappings to get the Mapping from current Frame of the + second region to the base Frame of the first Region. */ + map = (AstMapping *) astCmpMap( cmap, map_reg1, 1, "", status ); + +/* Get a mesh of points covering the second Region. These points are + within the current Frame of the second Region. */ + reg2_mesh = astRegMesh( reg2 ); + +/* Transform this mesh into the base Frame of the first Region. */ + ps1 = astTransform( map, reg2_mesh, 1, NULL ); + +/* Check there are some good points in the transformed pointset. */ + good = 0; + np = astGetNpoint( ps1 ); + nc = astGetNcoord( ps1 ); + ptr1 = astGetPoints( ps1 ); + if( ptr1 ) { + for( i = 0; i < nc && !good; i++ ) { + for( j = 0; j < np; j++ ) { + if( ptr1[ i ][ j ] != AST__BAD ) { + good = 1; + break; + } + } + } + } + +/* If the transformed mesh contains no good points, swap the regions and + try again. */ + if( !good ) { + fs = astAnnul( fs ); + frm_reg1 = astAnnul( frm_reg1 ); + map_reg1 = astAnnul( map_reg1 ); + cmap = astAnnul( cmap ); + map = astAnnul( map ); + reg2_mesh = astAnnul( reg2_mesh ); + ps1 = astAnnul( ps1 ); + + if( first ) { + first = 0; + + if( !bnd_that ) { + reg1 = this; + reg2 = that; + bnd1 = bnd_this; + bnd2 = bnd_that; + reg1_neg = this_neg; + reg2_neg = that_neg; + } else { + reg1 = that; + reg2 = this; + bnd1 = bnd_that; + bnd2 = bnd_this; + reg1_neg = that_neg; + reg2_neg = this_neg; + } + goto L1; + + } else { + return 0; + } + } + +/* Also transform the Region describing the positional uncertainty within + the second supplied Region into the base Frame of the first supplied + Region. */ + unc = astGetUncFrm( reg2, AST__CURRENT ); + bfrm_reg1 = astGetFrame( reg1->frameset, AST__BASE ); + unc1 = astMapRegion( unc, map, bfrm_reg1 ); + +/* See if all points within this transformed mesh fall on the boundary of + the first Region, to within the joint uncertainty of the two Regions. If + so the two Regions have equivalent boundaries. We can only do this is + the first region is bounded. */ + if( astRegPins( reg1, ps1, unc1, &mask ) && good ) { + +/* If the boundaries are equivalent, the Regions are either identical or + are mutually exclusive. To distinguish between these cases, we + looked at the Bounded attributes. If the Bounded attribute is the same + for both Regions then they are identical, otherwise they are mutually + exclusive. */ + result = ( ( !reg1_neg && bnd1 ) == ( !reg2_neg && bnd2 ) ) ? 5 : 6; + +/* If the boundaries of the two Regions are not equivalent. */ + } else { + +/* Create a new PointSet containing those points from the mesh which are + not on the boundary of the first Region. These points are identified by + the mask array created by the astRegPins method above. */ + reg2_submesh = GetSubMesh( mask, reg2_mesh, status ); + +/* Transform the points in the submesh of the second Region into the + current Frame of the first Region. */ + (void ) astAnnul( ps1 ); + ps1 = astTransform( cmap, reg2_submesh, 1, NULL ); + +/* Transform this submesh using the first Region as a Mapping. Any points + outside the first region will be set bad in the output PointSet. */ + ps2 = astTransform( (AstMapping *) reg1, ps1, 1, NULL ); + +/* Get the number of axes and points in this PointSet. */ + nc = astGetNcoord( ps2 ); + np = astGetNpoint( ps2 ); + +/* Note if there were any common points (i.e. points on the boundary of + both regions). */ + touch = ( astGetNpoint( reg2_mesh ) != np ); + +/* Get pointers to the axis data in this PointSet, and check they can be + used safely. */ + ptr = astGetPoints( ps2 ); + if( astOK ) { + +/* Loop round all points checking if the axis values are bad. We want a + flag saying if there are any good axis values and another flag saying if + there are any bad axis values. */ + allbad = 1; + allgood = 1; + for( iax = 0; iax < nc; iax++ ) { + p = ptr[ iax ]; + for( ip = 0; ip < np; ip++,p++ ) { + if( *p == AST__BAD ) { + allgood = 0; + if( !allbad ) break; + } else { + allbad = 0; + if( !allgood ) break; + } + } + } + +/* If the entire mesh of the (potentially negated) second Region was either + on the boundary of, or inside, the (potentially negated) first region, + determine the result depending on whether the regions have been + negated and whether they are bounded. Check for impossible states (or + maybe just errors in my logic). */ + if( allgood ) { + +/* Second region has a mesh so it must be bounded. */ + if( !bnd2 && astOK ) { + astError( AST__INTER, "astOverlap(%s): Inconsistent " + "state 1 (internal AST programming error).", + status, astGetClass( this ) ); + +/* If the first region has been made bounded by negating it... */ + } else if( reg1_neg ) { + if( bnd1 ) { + +/* If the second region has been made bounded by negating it, then the + unnegated first region is completely inside the unnegated second region. */ + if( reg2_neg ) { + result = 2; + +/* If the second region was bounded without negating it, then there is + no overlap between the unnegated first region and the second region. */ + } else { + result = 1; + } + +/* If the first region has been negated then it should not be unbounded. + This is ensured by the nature of the code that sets the "this_neg" and + "that_neg" flags above. */ + } else if( astOK ) { + astError( AST__INTER, "astOverlap(%s): Inconsistent " + "state 2 (internal AST programming error).", + status, astGetClass( this ) ); + } + +/* If the first region was bounded without negating it, but the second + region was made bounded by negating it, there is partial overlap. */ + } else if( reg2_neg ) { + result = 4; + +/* If the first region was bounded without negating it, but the second + region was also bounded without negating it, the second region is + completely inside the first region. */ + } else { + result = 3; + } + +/* If part of the mesh of the second Region was inside the first region, + and part was outside, then there is partial ocverlap. */ + } else if( !allbad ) { + result = 4; + +/* If no part of the mesh of the (possibly negated) second Region was inside + the (possibly negated) first region ... */ + } else { + +/* First deal with cases where the first region is unbounded. */ + if( !bnd1 ) { + if( reg1_neg && astOK ) { + astError( AST__INTER, "astOverlap(%s): Inconsistent " + "state 5 (internal AST programming error).", + status, astGetClass( this ) ); + } else if( reg2_neg ){ + result = 2; + } else { + result = 1; + } + +/* The second region has a mesh so it must be bounded. */ + } else if( !bnd2 && astOK ) { + astError( AST__INTER, "astOverlap(%s): Inconsistent " + "state 6 (internal AST programming error).", + status, astGetClass( this ) ); + +/* So now we know both (possibly negated) regions are bounded. */ + } else { + +/* We know that none of the reg2 mesh points are inside the bounded reg1. + But this still leaves two cases: 1) reg1 could be contained completely + within reg2, or 2) there is no overlap between reg2 and reg1. To + distinguish between these two cases we use reg2 to transform a point + on the boundary of reg1. First get a mesh on the boundary of reg1. */ + reg1_mesh = astRegMesh( reg1 ); + +/* Transform this mesh into the coordinate system of the second Region. */ + ps3 = astTransform( cmap, reg1_mesh, 0, NULL ); + +/* Transform the points in this mesh using the second Region as a Mapping. + Any points outside the second region will be set bad in the output + PointSet. */ + ps4 = astTransform( (AstMapping *) reg2, ps3, 1, NULL ); + +/* Get pointers to the axis data in this PointSet,and check they can be + used safely. */ + ptr = astGetPoints( ps4 ); + if( astOK ) { + +/* Test the firts point and set a flag indicating if we are in case 1 (if + not, we must be in case 2). */ + case1 = ( ptr[ 0 ][ 0 ] != AST__BAD ); + +/* Apply logic similar to the other cases to determine the result. */ + if( reg1_neg ) { + if( case1 == ( reg2_neg != 0 ) ) { + result = 3; + } else { + result = 4; + } + } else { + if( case1 == ( reg2_neg != 0 ) ) { + result = 1; + } else { + result = 2; + } + } + } + +/* Free resources. */ + reg1_mesh = astAnnul( reg1_mesh ); + ps3 = astAnnul( ps3 ); + ps4 = astAnnul( ps4 ); + } + } + } + +/* If there was no intersection or overlap, but the regions touch, then we + consider there to be an intersection if either region is closed. */ + if( touch && result == 1 ) { + if( astGetClosed( this) || astGetClosed( that ) ) result = 4; + } + +/* Free resources.*/ + reg2_submesh = astAnnul( reg2_submesh ); + ps2 = astAnnul( ps2 ); + } + +/* Free resources.*/ + fs = astAnnul( fs ); + bfrm_reg1 = astAnnul( bfrm_reg1 ); + frm_reg1 = astAnnul( frm_reg1 ); + map_reg1 = astAnnul( map_reg1 ); + cmap = astAnnul( cmap ); + map = astAnnul( map ); + ps1 = astAnnul( ps1 ); + reg2_mesh = astAnnul( reg2_mesh ); + unc = astAnnul( unc ); + unc1 = astAnnul( unc1 ); + if( mask) mask = astFree( mask ); + } + fs0 = astAnnul( fs0 ); + +/* The returned value should take account of whether "this" or "that" is + the first Region. If "this" was used as the first Region, then the + result value calculated above is already correct. If "that" was used as + the first Region, then we need to change the result to swap "this" and + "that". */ + if( reg1 == that ) { + if( result == 2 ) { + result = 3; + } else if( result == 3 ) { + result = 2; + } + } + +/* Re-instate the original Negated flags. */ + if( this_neg ) astNegate( this ); + if( that_neg ) astNegate( that ); + +/* If not OK, return zero. */ + if( !astOK ) result = 0; + +/* Return the result. */ + return result; +} + +static void Overlay( AstFrame *template_frame, const int *template_axes, + AstFrame *result, int *status ) { +/* +* Name: +* Overlay + +* Purpose: +* Overlay the attributes of a template Region on to another Frame. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void Overlay( AstFrame *template, const int *template_axes, +* AstFrame *result, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astOverlay +* method inherited from the Frame class). + +* Description: +* This function overlays attributes from the current Frame of a +* Region on to another Frame, so as to over-ride selected +* attributes of that second Frame. Normally only those attributes +* which have been specifically set in the template will be +* transferred. This implements a form of defaulting, in which a +* Frame acquires attributes from the template, but retains its +* original attributes (as the default) if new values have not +* previously been explicitly set in the template. + +* Parameters: +* template +* Pointer to the template Region, for whose current Frame +* values should have been explicitly set for any attribute +* which is to be transferred. +* template_axes +* Pointer to an array of int, with one element for each axis of +* the "result" Frame (see below). For each axis in the result +* frame, the corresponding element of this array should contain +* the (zero-based) index of the axis in the current Frame of +* the template Region to which it corresponds. This array is +* used to establish from which template Frame axis any +* axis-dependent attributes should be obtained. +* +* If any axis in the result Frame is not associated with a +* template Frame axis, the corresponding element of this array +* should be set to -1. +* +* If a NULL pointer is supplied, the template and result axis +* indices are assumed to be identical. +* result +* Pointer to the Frame which is to receive the new attribute values. +* status +* Pointer to the inherited status variable. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the current Frame in the Region and invoke its + astOverlay method to overlay its attributes. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( ((AstRegion *) template_frame)->frameset, AST__CURRENT ); + astOverlay( fr, template_axes, result ); + fr = astAnnul( fr ); +} + +static void PermAxes( AstFrame *this_frame, const int perm[], int *status ) { +/* +* Name: +* PermAxes + +* Purpose: +* Permute the order of a Region's axes. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void PermAxes( AstFrame *this, const int perm[], int *status ) + +* Class Membership: +* Region member function (over-rides the astPermAxes method +* inherited from the Frame class). + +* Description: +* This function permutes the order in which the axes in the +* current Frame of a Region occur. + +* Parameters: +* this +* Pointer to the Region. +* perm +* An array of int (with one element for each axis of the +* Region's current Frame) which lists the axes in their new +* order. Each element of this array should be a (zero-based) +* axis index identifying the axes according to their old +* (un-permuted) order. +* status +* Pointer to the inherited status variable. + +* Notes: +* - Only genuine permutations of the axis order are permitted, so +* each axis must be referenced exactly once in the "perm" array. +* - If more than one axis permutation is applied to the same Frame +* in a Region, the effects are cumulative. +*/ + +/* Local Variables: */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Invoke the astPermAxes method on the encapsulated FrameSet. */ + astPermAxes( this->frameset, perm ); + +} + +static AstFrame *PickAxes( AstFrame *this_frame, int naxes, const int axes[], + AstMapping **map, int *status ) { +/* +* Name: +* PickAxes + +* Purpose: +* Create a new Frame by picking axes from a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstFrame *PickAxes( AstFrame *this, int naxes, const int axes[], +* AstMapping **map, int *status ) + +* Class Membership: +* Region member function (over-rides the astPickAxes protected +* method inherited from the Frame class). + +* Description: +* This function creates a new Frame whose axes are copies of axes +* picked from the encapsulated Frame of an existing Region. Other +* Frame attributes are also copied from this existing Frame to the +* new Frame. Zero or more of the original axes may be picked in +* any order, but each can be used only once. Additional axes (with +* default characteristics) may be included in the new Frame if +* required. +* +* Optionally, a Mapping that converts between the original Frame's +* axes and those of the new Frame may also be returned. + +* Parameters: +* this +* Pointer to the Region. +* naxes +* The number of axes required in the new Frame. +* axes +* Pointer to an array of int with naxes elements. This should +* contain (zero based) axis indices specifying the axes which +* are to be included in the new Frame, in the order +* required. Each axis index may occur only once. +* +* If additional (default) axes are also to be included, the +* corresponding elements of this array should be set to -1. +* map +* Address of a location to receive a pointer to a new +* Mapping. This will be a PermMap (or a UnitMap as a special +* case) that describes the axis permutation that has taken +* place between the current Frame of the Region and the new +* Frame. The forward transformation will convert from the +* original Region's axes to the new one's, and vice versa. +* +* If this Mapping is not required, a NULL value may be supplied +* for this parameter. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* Pointer to the new Frame. + +* Notes: +* - The class of object returned may differ from that of the +* original current Frame, depending on which axes are +* selected. For example, if a single axis is picked from a +* SkyFrame (which always has two axes), the resulting Frame cannot +* be a valid SkyFrame, so will revert to the parent class (Frame) +* instead. +* - The new Frame contains a deep copy of all the data selected +* from the original current Frame. Modifying the new Frame will +* therefore not affect the Region or the Frames it contains. +* - A NULL pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *cfrm; /* Current Frame from input Region */ + AstFrame *frame; /* Pointer to Frame to be returned */ + AstMapping *cbmap; /* Base->current Mapping from input Region */ + AstMapping *fsmap; /* Mapping from selected current to base axes */ + AstRegion *breg; /* Region spanning selected base Frame axes */ + AstRegion *creg; /* Region spanning selected current Frame axes */ + AstRegion *this; /* Pointer to Region structure */ + int *base_axes; /* Holds selected base frame axis indices */ + int def; /* Were any default axes requested? */ + int i; /* Axis index */ + int nbase; /* No. of selected base Frame axes */ + +/* Initialise the returned pointers. */ + if ( map ) *map = NULL; + frame = NULL; + +/* Check the global error status. */ + if ( !astOK ) return frame; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Check that a valid set of axes is being selected . */ + astValidateAxisSelection( this, naxes, axes, "astPickAxes" ); + +/* Pick the required axes from the current Frame of the encapsulated + FrameSet. */ + cfrm = astGetFrame( this->frameset, AST__CURRENT ); + frame = astPickAxes( cfrm, naxes, axes, map ); + +/* See if any default axes are to be included in the returned Frame. */ + def = 0; + for( i = 0; i < naxes; i++ ) { + if( axes[ i ] < 0 ) def = 1; + } + +/* Regions cannot yet include extra default axes in the returned Frame + so return a basic Frame if any default axes were requested. */ + if( ! def ) { + +/* We now see if the requested set of current Frame axes correspond to a + unique set of base Frame axes. If they do, we may be able to return a + Region spanning the selected axes rather than just a Frame. The check + is performed by attempting to split the current->base Mapping. */ + cbmap = astGetMapping( this->frameset, AST__CURRENT, AST__BASE ); + base_axes = astMapSplit( cbmap, naxes, axes, &fsmap ); + +/* Check the Mapping could be split. */ + if( base_axes ) { + +/* Store the number of base Frame axes that correspond to the requested + set of current Frame axes. */ + nbase = astGetNout( fsmap ); + +/* Attempt to create a new Region that spans the corresponding set of + base Frame axes. */ + breg = astRegBasePick( this, nbase, base_axes ); + if( breg ) { + +/* Use the split Mapping to map the base Frame region into the requested + Frame. We invert the "fsmap" first so that it maps the selected base + Frame axes into the selected current Frame axes. */ + astInvert( fsmap ); + creg = astMapRegion( breg, fsmap, frame ); + +/* Copy properties from the old Region to the new Region. */ + astRegOverlay( creg, this, 0 ); + +/* Return this new Region in place of the simple Frame found above. */ + (void) astAnnul( frame ); + frame = (AstFrame *) creg; + +/* Free resources */ + breg = astAnnul( breg ); + } + fsmap = astAnnul( fsmap ); + base_axes = astFree( base_axes ); + } + cbmap = astAnnul( cbmap ); + } + cfrm = astAnnul( cfrm ); + +/* If an error occurred, annul the Mapping pointer (if requested) and + the new Frame pointer. */ + if ( !astOK ) { + if ( map ) *map = astAnnul( *map ); + frame = astAnnul( frame ); + } + +/* Return the pointer to the new Frame. */ + return frame; +} + +static void RegBaseBox( AstRegion *this, double *lbnd, double *ubnd, int *status ){ +/* +*+ +* Name: +* astRegBaseBox + +* Purpose: +* Returns the bounding box of an un-negated Region in the base Frame of +* the encapsulated FrameSet. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astRegBaseBox( AstRegion *this, double *lbnd, double *ubnd ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns the upper and lower axis bounds of a Region in +* the base Frame of the encapsulated FrameSet, assuming the Region +* has not been negated. That is, the value of the Negated attribute +* is ignored. + +* Parameters: +* this +* Pointer to the Region. +* lbnd +* Pointer to an array in which to return the lower axis bounds +* covered by the Region in the base Frame of the encapsulated +* FrameSet. It should have at least as many elements as there are +* axes in the base Frame. +* ubnd +* Pointer to an array in which to return the upper axis bounds +* covered by the Region in the base Frame of the encapsulated +* FrameSet. It should have at least as many elements as there are +* axes in the base Frame. + +*- +*/ + +/* Check the inherited status. */ + if( !astOK ) return; + +/* This abstract implementation simply reports an error. All sub-classes of + Region should over-ride this to return appropriate values. */ + astError( AST__INTER, "astRegBaseBox(%s): The %s class does not implement " + "the astRegBaseBox method inherited from the Region class " + "(internal AST programming error).", status, astGetClass( this ), + astGetClass( this ) ); +} + +static void RegBaseBox2( AstRegion *this, double *lbnd, double *ubnd, int *status ){ +/* +*+ +* Name: +* astRegBaseBox2 + +* Purpose: +* Returns the bounding box of an un-negated Region in the base Frame of +* the encapsulated FrameSet. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astRegBaseBox2( AstRegion *this, double *lbnd, double *ubnd ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function is similar to astRegBaseBox in that it returns the +* upper and lower axis bounds of a Region in the base Frame of the +* encapsulated FrameSet. But, in addition to assuming that the +* supplied Region has not been negated, it also assumes that any +* component Regions contained within the supplied Region have not been +* negated. + +* Parameters: +* this +* Pointer to the Region. +* lbnd +* Pointer to an array in which to return the lower axis bounds +* covered by the Region in the base Frame of the encapsulated +* FrameSet. It should have at least as many elements as there are +* axes in the base Frame. +* ubnd +* Pointer to an array in which to return the upper axis bounds +* covered by the Region in the base Frame of the encapsulated +* FrameSet. It should have at least as many elements as there are +* axes in the base Frame. + +*- +*/ + +/* This base class implementation simply calls astRegBaseBox. Sub-classes + which contain component Regions should override it. */ + astRegBaseBox( this, lbnd, ubnd ); + +} + +static AstPointSet *RegBaseGrid( AstRegion *this, int *status ){ +/* +*+ +* Name: +* astRegBaseGrid + +* Purpose: +* Return a PointSet containing points spread through the volume of a +* Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstPointSet *astRegBaseGrid( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a PointSet containing a set of points spread +* through the volume of the Region. The points refer to the base Frame of +* the encapsulated FrameSet. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* Pointer to the PointSet. If the Region is unbounded, a NULL pointer +* will be returned. + +* Notes: +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. +*- +*/ + +/* Local Variables: */ + AstBox *box; + AstFrame *frmb; + AstPointSet *ps1; + AstPointSet *ps2; + AstPointSet *result; + double **ptr2; + double **ptr; + double *lbnd; + double *ubnd; + int good; + int ic; + int ip; + int ipr; + int meshsize; + int naxb; + int np; + int npnt2; + int ntry; + +/* Initialise */ + result= NULL; + +/* Check the local error status. */ + if ( !astOK ) return NULL; + +/* If the Region structure contains a pointer to a PointSet holding + positions spread over the volume of the Region in the base Frame, + return it. */ + if( this->basegrid ) { + result = astClone( this->basegrid ); + +/* Otherwise, check the Region is bounded. */ + } else if( astGetBounded( this ) ) { + +/* Get the original MeshSize attribute. */ + meshsize = astGetMeshSize( this ); + +/* Get the base Frame bounding box. */ + naxb = astGetNin( this->frameset ); + lbnd = astMalloc( sizeof( double )*(size_t)naxb ); + ubnd = astMalloc( sizeof( double )*(size_t)naxb ); + astRegBaseBox( this, lbnd, ubnd ); + +/* Create a Box covering this bounding box. */ + frmb = astGetFrame( this->frameset, AST__BASE ); + box = astBox( frmb, 1, lbnd, ubnd, NULL, "", status ); + +/* Loop until we have a grid of nearly the right size. Make at most three + attempts. */ + ipr = 0; + np = meshsize; + ntry = 0; + while( ntry++ < 3 ) { + +/* Copy the MeshSize attribute to the new Box since this will be used by + the invocation of astRegBaseGrid below. */ + astSetMeshSize( box, np ); + +/* Invoke the Box astRegGrid method. Note, the Box class overrides this + implementation of astRegBaseGrid and does not (must not) invoke this + implementation, in order to avoid an infinite loop. */ + ps1 = astRegBaseGrid( box ); + +/* Some of the base Frame points in the above bounding box will fall outside + the supplied Region. Use the Region as a Mapping to determine which they + are. Since the points are base Frame points, use astBTransform rather + than astTransform. */ + ps2 = astBTransform( this, ps1, 1, NULL ); + +/* We now create a PointSet which is a copy of "ps2" but with all the bad + points (i.e. the points in the bounding box grid which are not inside + the supplied Region) removed. Create a result PointSet which is the same + size as "ps2", then copy just the good points from "ps2" to the result + PointSet, keeping a record of the number of points copied. */ + ptr2 = astGetPoints( ps2 ); + npnt2 = astGetNpoint( ps2 ); + result = astPointSet( npnt2, naxb, "", status ); + ptr = astGetPoints( result ); + if( astOK ) { + +/* Initialise the index of the next point to be stored in "result". */ + ipr = 0; + +/* Loop round all points in "ps2" */ + for( ip = 0; ip < npnt2; ip++ ) { + +/* Copy each axis value for this point from "ps2" to "result". If a bad + axis value is encountered, flag that the point is bad and break out of + the axis loop. */ + good = 1; + for( ic = 0; ic < naxb; ic++ ) { + if( ptr2[ ic ][ ip ] == AST__BAD ) { + good = 0; + break; + } else { + ptr[ ic ][ ipr ] = ptr2[ ic ][ ip ]; + } + } + +/* If the current point has no bad axis values, increment the index of + the next point to be stored in "result". */ + if( good ) ipr++; + } + } + +/* Free resources */ + ps1 = astAnnul( ps1 ); + ps2 = astAnnul( ps2 ); + +/* Leave the loop if an error has occurred. */ + if( !astOK ) break; + +/* If the number of points in the grid is within 5% of the target value, + it is good enough, so break. */ + if( fabs( (double)( ipr - meshsize ) )/meshsize < 0.05 ) break; + +/* Otherwise, adjust the target size of the grid by the ratio by which it + is in error. Don't do this if we have reached the maximum number of + re-tries. */ + if( ntry < 3 ) { + if( ipr == 0 ) { + np *= 10; + } else { + np *= (double)meshsize/(double)ipr; + } + result = astAnnul( result ); + } + } + +/* Truncate the "result" PointSet to exclude any unused space at the end + of the axis values arrays. */ + if( astOK ) astSetNpoint( result, ipr ); + +/* Free resources */ + lbnd = astFree( lbnd ); + ubnd = astFree( ubnd ); + frmb = astAnnul( frmb ); + box = astAnnul( box ); + +/* Cache the new grid for future use. */ + if( astOK ) this->basegrid = astClone( result ); + } + +/* Annul the result if an error occurred. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the result */ + return result; +} + +static AstRegion **RegSplit( AstRegion *this, int *nlist, int *status ){ +/* +*+ +* Name: +* astRegSplit + +* Purpose: +* Split a Region into a list of disjoint component Regions. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstRegion **astRegSplit( AstRegion *this, int *nlist ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function splits the supplied Region into a set of disjoint +* component Regions. If the Region cannot be split, then the returned +* array contains only one pointer - a clone of the supplied Region +* pointer. + +* Parameters: +* this +* Pointer to the Region. +* nlist +* Pointer to an int in which to return the number of elements in +* the returned array. + +* Returned Value: +* Pointer to dynamically alloctaed memory holding an array of Region +* pointers. The length of this array is given by the value returned +* in "*nlist". The pointers in the returned array should be annulled +* using astAnnul when no longer needed, and the memory used to hold +* the array should be freed using astFree. + +* Notes: +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. +*- +*/ + +/* Local Variables; */ + AstRegion **result; + +/* Initialise. */ + result = NULL; + *nlist = 0; + +/* Check the local error status. */ + if ( !astOK ) return result; + +/* The base class just returns an array containing a clone of the + supplied Region pointer. */ + result = astMalloc( sizeof( *result ) ); + if( astOK ) { + result[ 0 ] = astClone( this ); + *nlist = 1; + } + + if( !astOK ) { + result = astFree( result ); + *nlist = 0; + } + + return result; +} + +static AstPointSet *RegBaseMesh( AstRegion *this, int *status ){ +/* +*+ +* Name: +* astRegBaseMesh + +* Purpose: +* Return a PointSet containing points spread around the boundary of a +* Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstPointSet *astRegBaseMesh( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a PointSet containing a set of points on the +* boundary of the Region. The points refer to the base Frame of +* the encapsulated FrameSet. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* Pointer to the PointSet. The axis values in this PointSet will have +* associated accuracies derived from the uncertainties which were +* supplied when the Region was created. +* +* If the Region has no boundary (i.e. is equivalent to a NullRegion), the +* returned PointSet will contain a single point with a value of AST__BAD +* on every axis. + +* Notes: +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. +*- +*/ + +/* Check the local error status. */ + if ( !astOK ) return NULL; + +/* This abstract method must be over-ridden by each concrete sub-class. + Report an error if this null imlementation is called.*/ + astError( AST__INTER, "astRegBaseMesh(%s): The %s class does not implement " + "the astRegBaseMesh method inherited from the Region class " + "(internal AST programming error).", status, astGetClass( this ), + astGetClass( this ) ); + return NULL; +} + +static AstRegion *RegBasePick( AstRegion *this, int naxes, const int *axes, + int *status ){ +/* +*+ +* Name: +* astRegBasePick + +* Purpose: +* Return a Region formed by picking selected base Frame axes from the +* supplied Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstRegion *astRegBasePick( AstRegion *this, int naxes, const int *axes ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function attempts to return a Region that is spanned by selected +* axes from the base Frame of the encapsulated FrameSet of the supplied +* Region. This may or may not be possible, depending on the class of +* Region. If it is not possible a NULL pointer is returned. + +* Parameters: +* this +* Pointer to the Region. +* naxes +* The number of base Frame axes to select. +* axes +* An array holding the zero-based indices of the base Frame axes +* that are to be selected. + +* Returned Value: +* Pointer to the Region, or NULL if no region can be formed. + +* Notes: +* - This base implementation returns NULL unless all base Frame axes +* are selected (possibly in a permuted order). +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. +*- +*/ +/* Local Variables: */ + AstFrame *fr; /* Pointer to the Region's base Frame */ + AstRegion *result; /* The returned Region pointer */ + int found; /* Has the current axis index been found yet? */ + int i; /* Axis index */ + int j; /* Index into the "axes" array */ + int nax; /* No. of base Frame axes */ + int ok; /* Are we doing a genuine axis permutation? */ + int unit; /* Is the axis permutation a unit map? */ + +/* Initialise */ + result = NULL; + +/* Check the local error status. */ + if ( !astOK ) return result; + +/* Get a pointer to the base Frame int he encapsulated FrameSet. */ + fr = astGetFrame( this->frameset, AST__BASE ); + +/* See how many axes it has. We only proceed if we are selecting all axes + in the base Frame. */ + nax = astGetNaxes( fr ); + if( nax == naxes ) { + +/* We now check that the axes array is a genuine permutation of all axes. + This means that all axis indices must occur once, and only once, within + the "axes" array. Look for each axis index in turn. */ + unit = 1; + ok = 1; + for( i = 0; i < nax && ok; i++ ) { + +/* Check each element of the axes array to see if it holds the axis index + currently being looked for. */ + found = 0; + for( j = 0; j < nax; j++ ) { + +/* If so, if this axis index has already been found, break out of the + loop. */ + if( axes[ j ] == i ) { + if( found ) { + ok = 0; + break; + } + found = 1; + +/* Note if we do not have a unit map (i.e. each axis is permuted onto itself). */ + if( i != j ) unit = 0; + } + } + +/* If the axis index was not found, we do not have a genuine axis + permutation. */ + if( !found ) ok = 0; + } + +/* If we have a genuine axis permutation, create a Region which is a copy + of the supplied region and set it to represent its base Frame. */ + if( ok ) { + result = astCopy( this ); + astSetRegFS( result, fr ); + +/* If the axis selection is not equivalent to a unit mapping, we now + permute the axes. */ + if( !unit ) astPermAxes( result, axes ); + } + } + +/* Free resources. */ + fr = astAnnul( fr ); + +/* Returned the result. */ + return result; +} + +static double *RegCentre( AstRegion *this, double *cen, double **ptr, + int index, int ifrm, int *status ){ +/* +*+ +* Name: +* astRegCentre + +* Purpose: +* Re-centre a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* double *astRegCentre( AstRegion *this, double *cen, double **ptr, +* int index, int ifrm ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function shifts the centre of the supplied Region to a +* specified position, or returns the current centre of the Region. + +* Parameters: +* this +* Pointer to the Region. +* cen +* Pointer to an array of axis values, giving the new centre. +* Supply a NULL value for this in order to use "ptr" and "index" to +* specify the new centre. +* ptr +* Pointer to an array of pointers, one for each axis in the Region. +* Each pointer locates an array of axis values. This is the format +* returned by the PointSet method astGetPoints. Only used if "cen" +* is NULL. +* index +* The index of the point within the arrays identified by "ptr" at +* which is stored the coords for the new centre position. Only used +* if "cen" is NULL. +* ifrm +* Should be AST__BASE or AST__CURRENT. Indicates whether the centre +* position is supplied and returned in the base or current Frame of +* the FrameSet encapsulated within "this". + +* Returned Value: +* If both "cen" and "ptr" are NULL then a pointer to a newly +* allocated dynamic array is returned which contains the centre +* coords of the Region. This array should be freed using astFree when +* no longer needed. If either of "ptr" or "cen" is not NULL, then a +* NULL pointer is returned. + +* Notes: +* - Any bad (AST__BAD) centre axis values are ignored. That is, the +* centre value on such axes is left unchanged. +* - Some Region sub-classes do not have a centre. Such classes will report +* an AST__INTER error code if this method is called with either "ptr" or +* "cen" not NULL. If "ptr" and "cen" are both NULL, then no error is +* reported if this method is invoked on a Region of an unsuitable class, +* but NULL is always returned. + +*- +*/ + +/* Local Variables: */ + double *result; + +/* Initialise */ + result = NULL; + +/* Check the local error status. */ + if ( !astOK ) return result; + +/* This abstract method must be over-ridden by each concrete sub-class + which allows the centre to be shifted. Report an error if this null + imlementation is called to set a new centre. If it is called to + enquire the current centre, then return a NULL pointer. */ + if( ptr || cen ) astError( AST__INTER, "astRegCentre(%s): The %s " + "class does not implement the astRegCentre method " + "inherited from the Region class (internal AST " + "programming error).", status, astGetClass( this ), + astGetClass( this ) ); + + return NULL; +} + +static void RegClearAttrib( AstRegion *this, const char *aattrib, + char **base_attrib, int *status ) { +/* +*+ +* Name: +* astRegClearAttrib + +* Purpose: +* Clear an attribute value for a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astRegClearAttrib( AstRegion *this, const char *aattrib, +* char **base_attrib ) + +* Class Membership: +* Region virtual function + +* Description: +* This function clears the value of a named attribute in both the base +* and current Frame in the FrameSet encapsulated within a Region, without +* remapping either Frame. +* +* No error is reported if the attribute is not recognised by the base +* Frame. + +* Parameters: +* this +* Pointer to the Region. +* aattrib +* Pointer to a null terminated string holding the attribute name. +* base_attrib +* Address of a location at which to return a pointer to the null +* terminated string holding the attribute name which was cleared in +* the base Frame of the encapsulated FrameSet. This may differ from +* the supplied attribute if the supplied attribute contains an axis +* index and the current->base Mapping in the FrameSet produces an +* axis permutation. The returned pointer should be freed using +* astFree when no longer needed. A NULL pointer may be supplied in +* which case no pointer is returned. +*- +*/ + +/* Local Variables: */ + AstFrame *frm; + AstMapping *junkmap; + AstMapping *map; + AstRegion *unc; + char *attrib; + char *battrib; + char buf1[ 100 ]; + int *outs; + int axis; + int baxis; + int i; + int len; + int nc; + int rep; + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Produce a lower case version of the attribute name string */ + nc = strlen( aattrib ); + attrib = astMalloc( nc + 1 ); + for( i = 0; i < nc; i++ ) attrib[ i ] = tolower( aattrib[ i ] ); + attrib[ nc ] = 0; + +/* Clear the attribute in the current Frame in the encapsulated FrameSet. + Use the protected astClearAttrib method which does not cause the Frame + to be remapped within the FrameSet. */ + frm = astGetFrame( this->frameset, AST__CURRENT ); + astClearAttrib( frm, attrib ); + frm = astAnnul( frm ); + +/* Indicate that we should use the supplied attribute name with the base Frame. */ + battrib = NULL; + +/* If the attribute name contains an axis number, we need to create a new + attribute name which refers to the corresponding base Frame axis + (since the base<->current Mapping may permute the axes). First parse the + supplied attribute name to locate any axis index. */ + len = strlen( attrib ); + if( nc = 0, ( 2 == astSscanf( attrib, "%[^(](%d) %n", buf1, &axis, + &nc ) ) && ( nc >= len ) ) { + +/* If found, convert the axis index from one-based to zero-based. */ + axis--; + +/* See if the specified current Frame axis is connected to one and only + one base Frame axis. If so, get the index of the base Frame axis. */ + map = astGetMapping( this->frameset, AST__CURRENT, AST__BASE ); + outs = astMapSplit( map, 1, &axis, &junkmap ); + if( junkmap && astGetNout( junkmap ) == 1 ) { + baxis = outs[ 0 ]; + +/* If the base Frame axis index is different to the current Frame axis + index, create a new attribute name string using the base Frame axis index. */ + if( baxis != axis ) { + battrib = astMalloc( strlen( attrib ) + 10 ); + if( battrib ) sprintf( battrib, "%s(%d)", buf1, baxis + 1 ); + } + +/* If there is no one base Frame axis which corresponds to the supplied + current Frame axis, report an error. */ + } else if( astOK ) { + astError( AST__INTER, "astRegClearAttrib(%s): Unable to clear " + "attribute \"%s\" in the base Frame of the %s", status, + astGetClass( this ), attrib, astGetClass( this ) ); + astError( AST__INTER, "There is no base Frame axis corresponding " + "to current Frame axis %d\n", status, axis + 1 ); + } + +/* Free resources */ + outs = astFree( outs ); + if( junkmap ) junkmap = astAnnul( junkmap ); + map = astAnnul( map ); + } + +/* Clear the appropriate attribute name in the base Frame. This time ensure + that any error caused by the attribute name is annulled. Also clear it in + any uncertainty Region (the current Frame of the uncertainty Region is + assumed to be equivalent to the base Frame of the parent Region). */ + frm = astGetFrame( this->frameset, AST__BASE ); + if( frm ) { + rep = astReporting( 0 ); + astClearAttrib( frm, battrib ? battrib : attrib ); + if( astTestUnc( this ) ) { + unc = astGetUncFrm( this, AST__BASE ); + astRegClearAttrib( unc, battrib ? battrib : attrib, NULL ); + unc = astAnnul( unc ); + } + if( astStatus == AST__BADAT ) astClearStatus; + astReporting( rep ); + } + frm = astAnnul( frm ); + +/* If required return the modified base Frame attribute name. Otherwise, + free it. */ + if( base_attrib ) { + if( battrib ) { + *base_attrib = battrib; + } else { + *base_attrib = astStore( NULL, attrib, strlen( attrib ) + 1 ); + } + } else { + battrib = astFree( battrib ); + } + +/* Since the base Frame has been changed, any cached information calculated + on the basis of the base Frame properties may no longer be up to date. */ + astResetCache( this ); + +/* Free resources. */ + attrib = astFree( attrib ); + +} + +static AstPointSet *RegGrid( AstRegion *this, int *status ){ +/* +*+ +* Name: +* astRegGrid + +* Purpose: +* Return a PointSet containing points spread through the volume of a +* Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstPointSet *astRegGrid( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a PointSet containing a mesh of points spread +* throughout the volume of the Region. The points refer to the current +* Frame of the encapsulated FrameSet. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* Pointer to the PointSet. The axis values in this PointSet will have +* associated accuracies derived from the uncertainties which were +* supplied when the Region was created. Annul the pointer using +* astAnnul when it is no longer needed. + +* Notes: +* - It should not be assumed that the returned points are evenly +* spaced withint he volume. +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. +*- +*/ + +/* Local Variables; */ + AstMapping *map; /* Base -> current Frame Mapping */ + AstPointSet *result; /* Pointer to returned PointSet */ + +/* Initialise the returned pointer */ + result = NULL; + +/* Check the local error status. */ + if ( !astOK ) return result; + +/* If the Region structure does not contain a pointer to a PointSet holding + positions evenly spread over the volume of the Region in the base + Frame, create one now. Note, we cannot cache the grid in the current + Frame in this way since the current Frame grid depends on the proprties + of the current Frame (e.g. System) which can be changed at any time. */ + if( !this->basegrid ) this->basegrid = astRegBaseGrid( this ); + +/* Get the simplified base->current Mapping */ + map = astRegMapping( this ); + +/* If the Mapping is a UnitMap, just return a clone of the PointSet + pointer stored in the Region structure. */ + if( astIsAUnitMap( map ) ){ + result = astClone( this->basegrid ); + +/* Otherwise, create a new PointSet holding the above points transformed + into the current Frame. */ + } else { + result = astTransform( map, this->basegrid, 1, NULL ); + } + +/* Free resources.*/ + map = astAnnul( map ); + +/* If an error has occurred, annul the returned PointSet. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the result. */ + return result; +} + +static AstPointSet *RegMesh( AstRegion *this, int *status ){ +/* +*+ +* Name: +* astRegMesh + +* Purpose: +* Return a PointSet containing points spread over the boundary of a +* Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstPointSet *astRegMesh( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a PointSet containing a mesh of points on the +* boundary of the Region. The points refer to the current Frame of +* the encapsulated FrameSet. + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* Pointer to the PointSet. The axis values in this PointSet will have +* associated accuracies derived from the uncertainties which were +* supplied when the Region was created. Annul the pointer using +* astAnnul when it is no longer needed. + +* Notes: +* - It should not be assumed that the returned points are evenly +* spaced on the boundary. +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. +*- +*/ + +/* Local Variables; */ + AstMapping *map; /* Base -> current Frame Mapping */ + AstPointSet *bmesh; /* Base Frame mesh */ + AstPointSet *result; /* Pointer to returned PointSet */ + +/* Initialise the returned pointer */ + result = NULL; + +/* Check the local error status. */ + if ( !astOK ) return result; + +/* Get a pointer to a PointSet holding positions evenly spread over the + boundary of the Region in the base Frame. */ + bmesh = astRegBaseMesh( this ); + +/* Get the simplified base->current Mapping */ + map = astRegMapping( this ); + +/* If the Mapping is a UnitMap, just return a clone of the mesh PointSet + pointer. */ + if( astIsAUnitMap( map ) ){ + result = astClone( bmesh ); + +/* Otherwise, create a new PointSet holding the above points transformed + into the current Frame. */ + } else { + result = astTransform( map, bmesh, 1, NULL ); + } + +/* Free resources.*/ + bmesh = astAnnul( bmesh ); + map = astAnnul( map ); + +/* If an error has occurred, annul the returned PointSet. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the result. */ + return result; +} + +static int RegDummyFS( AstRegion *this, int *status ){ +/* +*+ +* Name: +* astRegDummyFS + +* Purpose: +* Check if a Region has a dummy FrameSet. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* int astRegDummyFS( AstRegion *this ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a flag indicating if the supplied Region has +* a dummy FrameSet. +* +* The astDump method for a Region may choose not to include the +* Region's FrameSet in the dump, depending on the value of the +* RegionFS attribute and the nature of the FrameSet. If the FrameSet +* is omitted from the Dump, then special action has to be taken when +* the dump is subsequently read in and used to re-create the Region. +* On encounterting such a dump, the astLoadRegion function will create +* a dummy FrameSet and associate it with the reconstructed Region. +* The new Region should not be used however until this dummy FrameSet +* has been replaced by the correct FrameSet. Performing this replacement +* is the responsibility of the parent class (i.e. the class which choose +* to omit the FrameSet from the dump). These will usually be Region +* classes which encapsulate other Regions, such as CmpRegion, Prism, +* Stc, etc. +* +* This function can be used by astLoad... methods in sub-classes to +* determine if a newly loaded component Region has a dummy FrameSet. If +* so the astLoad function should either use the astSetRegFS method to +* store a new FrameSet in the component Region. If the parent Region +* itself has a dummy FrameSet (i.e. is a component Region contained +* within a higher level Region) then it cannot do this and should +* ignore the presence of the dummy FrameSet (it then becomes the +* responsibility of hte parent Region to load appropriate FrameSets +* into all its components). + +* Parameters: +* this +* Pointer to the Region. + +* Returned Value: +* Non-zero if the Region has a dummy FrameSet. + +*- +*/ + +/* Check the inherited status. */ + if( !astOK ) return 0; + +/* The Ident attribute of the FrameSet will be set to DUMMY_FS if the + FrameSet is a dummy. */ + return !strcmp( astGetIdent( this->frameset ), DUMMY_FS ); +} + +static int RegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, + int **mask, int *status ){ +/* +*+ +* Name: +* astRegPins + +* Purpose: +* Check if a set of points fall on the boundary of a given Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* int astRegPins( AstRegion *this, AstPointSet *pset, AstRegion *unc, +* int **mask ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function returns a flag indicating if the supplied set of +* points all fall on the boundary of the given Region. +* +* Some tolerance is allowed, as specified by the uncertainty Region +* stored in the supplied Region "this", and the supplied uncertainty +* Region "unc" which describes the uncertainty of the supplied points. + +* Parameters: +* this +* Pointer to the Region. +* pset +* Pointer to the PointSet. The points are assumed to refer to the +* base Frame of the FrameSet encapsulated by "this". +* unc +* Pointer to a Region representing the uncertainties in the points +* given by "pset". The Region is assumed to represent the base Frame +* of the FrameSet encapsulated by "this". Zero uncertainity is assumed +* if NULL is supplied. +* mask +* Pointer to location at which to return a pointer to a newly +* allocated dynamic array of ints. The number of elements in this +* array is equal to the value of the Npoint attribute of "pset". +* Each element in the returned array is set to 1 if the +* corresponding position in "pset" is on the boundary of the Region +* and is set to zero otherwise. A NULL value may be supplied +* in which case no array is created. If created, the array should +* be freed using astFree when no longer needed. + +* Returned Value: +* Non-zero if the points all fall on the boundary of the given +* Region, to within the tolerance specified. Zero otherwise. + +*- +*/ + +/* Check the inherited status. */ + if( !astOK ) return 0; + +/* This abstract implementation simply reports an error. All sub-classes of + Region should over-ride this to return appropriate values. */ + astError( AST__INTER, "astRegPins(%s): The %s class does not implement " + "the astRegPins method inherited from the Region class " + "(internal AST programming error).", status, astGetClass( this ), + astGetClass( this ) ); + return 0; +} + +static void GetRegionBounds( AstRegion *this, double *lbnd, double *ubnd, int *status ){ +/* +*++ +* Name: +c astGetRegionBounds +f AST_GETREGIONBOUNDS + +* Purpose: +* Returns the bounding box of Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c void astGetRegionBounds( AstRegion *this, double *lbnd, double *ubnd ) +f CALL AST_GETREGIONBOUNDS( THIS, LBND, UBND, STATUS ) + +* Class Membership: +* Region method. + +* Description: +c This function +f This routine +* returns the upper and lower limits of a box which just encompasses +* the supplied Region. The limits are returned as axis values within +* the Frame represented by the Region. The value of the Negated +* attribute is ignored (i.e. it is assumed that the Region has not +* been negated). + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +c lbnd +f LBND() = DOUBLE PRECISION (Returned) +c Pointer to an +f An +* array in which to return the lower axis bounds covered by the Region. +* It should have at least as many elements as there are axes in the +* Region. If an axis has no lower limit, the returned value will +* be the largest possible negative value. +c ubnd +f UBND() = DOUBLE PRECISION (Returned) +c Pointer to an +f An +* array in which to return the upper axis bounds covered by the Region. +* It should have at least as many elements as there are axes in the +* Region. If an axis has no upper limit, the returned value will +* be the largest possible positive value. +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Notes: +* - The value of the Negated attribute is ignored (i.e. it is assumed that +* the Region has not been negated). +* - If an axis has no extent on an axis then the lower limit will be +* returned larger than the upper limit. Note, this is different to an +* axis which has a constant value (in which case both lower and upper +* limit will be returned set to the constant value). +* - If the bounds on an axis cannot be determined, AST__BAD is returned for +* both upper and lower bounds + +*-- +*/ + +/* Local Variables: */ + AstFrame *frm; /* Current Frame */ + AstMapping *smap; /* Simplified base -> current Mapping */ + AstPointSet *bmesh; /* PointSet holding base Frame mesh */ + AstPointSet *cmesh; /* PointSet holding current Frame mesh */ + double **bptr; /* Pointer to PointSet coord arrays */ + double **cptr; /* Pointer to PointSet coord arrays */ + double *blbnd; /* Lower bounds in base Frame */ + double *bubnd; /* Upper bounds in base Frame */ + double *p; /* Array of values for current axis */ + double width; /* Width of bounding box on i'th axis */ + int i; /* Axis count */ + int ip; /* Index of current corner */ + int j; /* Timer for low/high swaps */ + int jmax; /* Increment between low/high swaps */ + int lo; /* Assign low bound to next corner? */ + int nbase; /* Number of base Frame axes */ + int ncur; /* Number of current Frame axes */ + int npos; /* Number of box corners */ + +/* Check the inherited status. */ + if( !astOK ) return; + +/* Get the simplified base to current Mapping. */ + smap = astRegMapping( this ); + +/* If the simplified Mapping is a UnitMap, just store the base box bounds + in the returned arrays */ + if( astIsAUnitMap( smap ) ) { + astRegBaseBox( this, lbnd, ubnd ); + +/* Otherwise, we get a mesh of points over the boundary of the Region within + the base Frame, transform them into the current Frame, and find their bounds. */ + } else { + +/* If the Region is bounded, we can get a genuine mesh of points on the + boundary of the Region. */ + if( astGetBounded( this ) ) { + bmesh = astRegBaseMesh( this ); + +/* If the Region is not bounded, no mesh can be created so we use the + corners of the base frame bounding box instead. */ + } else { + +/* Get workspace to hold the bounds of the region within the base Frame. */ + nbase = astGetNin( smap ); + blbnd = astMalloc( sizeof( double )*nbase ); + bubnd = astMalloc( sizeof( double )*nbase ); + +/* Get the base Frame bounding box. */ + astRegBaseBox( this, blbnd, bubnd ); + +/* Get the number of corners in the base Frame bounding box. */ + npos = pow( 2, nbase ); + +/* Create a PointSet to hold the positions at the corners in the base + frame box. */ + bmesh = astPointSet( npos, nbase, " ", status ); + bptr = astGetPoints( bmesh ); + if( bptr ) { + +/* Store the coordinates of the box corners in the PointSet. */ + jmax = 1; + for( i = 0; i < nbase; i++ ) { + p = bptr[ i ]; + + lo = 1; + j = 0; + for( ip = 0; ip < npos; ip++,j++ ) { + if( j == jmax ) { + lo = 1 - lo; + j = 0; + } + p[ ip ] = lo ? blbnd[ i ] : bubnd[ i ]; + } + + jmax *= 2; + } + } + +/* Release resources. */ + blbnd = astFree( blbnd ); + bubnd = astFree( bubnd ); + } + +/* Create a new PointSet holding the above points transformed into the + current Frame. */ + cmesh = astTransform( smap, bmesh, 1, NULL ); + +/* There is a possibility that these points may span a singularity in the + coordinate system such as the RA=0 line in a SkyFrame. So ensure the + axis values are normalised into the shortest possible range. */ + frm = astGetFrame( this->frameset, AST__CURRENT ); + ncur = astGetNaxes( frm ); + + cptr = astGetPoints( cmesh ); + npos = astGetNpoint( cmesh ); + for( i = 0; i < ncur; i++ ) { + astAxNorm( frm, i+1, 1, npos, cptr[i] ); + } + +/* Get the axis bounds of this PointSet. */ + astBndPoints( cmesh, lbnd, ubnd ); + +/* There is again a possibility that these bounds may span a singularity in + the coordinate system such as the RA=0 line in a SkyFrame. So for each + axis we ensure the width (i.e. "ubnd-lbnd" ) is correct. */ + for( i = 0; i < ncur; i++ ) { + width = astAxDistance( frm, i + 1, lbnd[ i ], ubnd[ i ] ); + if( width != AST__BAD ) { + ubnd[ i ] = lbnd[ i ] + width; + } else { + ubnd[ i ] = AST__BAD; + lbnd[ i ] = AST__BAD; + } + } + +/* Release resources. */ + frm = astAnnul( frm ); + bmesh = astAnnul( bmesh ); + cmesh = astAnnul( cmesh ); + } + smap = astAnnul( smap ); +} + +static void GetRegionBounds2( AstRegion *this, double *lbnd, double *ubnd, int *status ){ +/* +*+ +* Name: +* astGetRegionBounds + +* Purpose: +* Returns the bounding box of Region. + +* Type: +* Protected virtual function. + +* Synopsis: +* #include "region.h" +* void astGetRegionBounds2( AstRegion *this, double *lbnd, double *ubnd ) + +* Class Membership: +* Region method. + +* Description: +* This function is like astGetRegionBounds, in that it returns the upper +* and lower limits of a box which just encompasses the supplied Region, +* as axis values within the Frame represented by the Region. But, in +* addition to assuming that the supplied Region has not been negated, it +* also assumes that any component Regions contained within the supplied +* Region have not been negated. + +* Parameters: +* this +* Pointer to the Region. +* lbnd +* Pointer to an array in which to return the lower axis bounds +* covered by the Region. It should have at least as many elements +* as there are axes in the Region. +* ubnd +* Pointer to an array in which to return the upper axis bounds +* covered by the Region. It should have at least as many elements +* as there are axes in the Region. + +* Notes: +* - The value of the Negated attribute is ignored (i.e. it is assumed that +* the Region has not been negated). The Nagated attributes of any +* component Regions are also ignored. + +*- +*/ + +/* Local Variables: */ + AstMapping *smap; /* Simplified base -> current Mapping */ + double *lbndb; /* Pointer to lower bounds on base box */ + double *ubndb; /* Pointer to upper bounds on base box */ + int i; /* Axis count */ + int nbase; /* Number of base Frame axes */ + int ncur; /* Number of current Frame axes */ + +/* Check the inherited status. */ + if( !astOK ) return; + +/* Find the number of axes in the base and current Frames of the + encapsulated FrameSet. */ + nbase = astGetNin( this->frameset ); + ncur = astGetNout( this->frameset ); + +/* Get the bounding box in the base Frame of the encapsulated FrameSet. */ + lbndb = astMalloc( sizeof( double )*(size_t) nbase ); + ubndb = astMalloc( sizeof( double )*(size_t) nbase ); + astRegBaseBox2( this, lbndb, ubndb ); + +/* Get the simplified base to current Mapping. */ + smap = astRegMapping( this ); + +/* Check pointers can be used safely. */ + if( smap ) { + +/* If the simplified Mapping is a UnitMap, just copy the base box bounds + to the returned arrays */ + if( astIsAUnitMap( smap ) ) { + for( i = 0; i < ncur; i++ ) { + lbnd[ i ] = lbndb[ i ]; + ubnd[ i ] = ubndb[ i ]; + } + +/* Otherwise, use astMapBox to find the corresponding current Frame + limits. */ + } else { + for( i = 0; i < ncur; i++ ) { + astMapBox( smap, lbndb, ubndb, 1, i, lbnd + i, ubnd + i, + NULL, NULL ); + } + } + } + +/* Release resources. */ + smap = astAnnul( smap ); + lbndb = astFree( lbndb ); + ubndb = astFree( ubndb ); +} + +static void GetRegionMesh( AstRegion *this, int surface, int maxpoint, + int maxcoord, int *npoint, double *points, + int *status ){ +/* +*++ +* Name: +c astGetRegionMesh +f AST_GETREGIONMESH + +* Purpose: +* Return a mesh of points covering the surface or volume of a Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c void astGetRegionMesh( AstRegion *this, int surface, int maxpoint, +c int maxcoord, int *npoint, double *points ) +f CALL AST_GETREGIONMESH( THIS, SURFACE, MAXPOINT, MAXCOORD, NPOINT, +f POINTS, STATUS ) + +* Class Membership: +* Region method. + +* Description: +c This function +f This routine +* returns the axis values at a mesh of points either covering the +* surface (i.e. boundary) of the supplied Region, or filling the +* interior (i.e. volume) of the Region. The number of points in +* the mesh is approximately equal to the MeshSize attribute. + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +c surface +f SURFACE = LOGICAL (Given) +c If non-zero, +f If .TRUE., +* the returned points will cover the surface or the Region. +* Otherwise, they will fill the interior of the Region. +c maxpoint +f MAXPOINT = INTEGER (Given) +* If zero, the number of points in the mesh is returned in +c "*npoint", +f NPOINT, +* but no axis values are returned and all other parameters are ignored. +* If not zero, the supplied value should be the length of the +c second dimension of the "points" +f first dimension of the POINTS +* array. An error is reported if the number of points in the mesh +* exceeds this number. +c maxcoord +f MAXCOORD = INTEGER (Given) +* The length of the +c first dimension of the "points" array. +f second dimension of the POINTS array. +* An error is reported if the number of axes in the supplied Region +* exceeds this number. +c npoint +f NPOINT = INTEGER (Returned) +c A pointer to an integer in which to return the +f The +* number of points in the returned mesh. +c points +f POINTS( MAXPOINT, MAXCOORD ) = DOUBLE PRECISION (Returned) +c The address of the first element in a 2-dimensional array of +c shape "[maxcoord][maxpoint]", in which to return the coordinate +c values at the mesh positions. These are stored such that the +c value of coordinate number "coord" for point number "point" is +c found in element "points[coord][point]". +f An array in which to return the coordinates values at the mesh +f positions. These are stored such that the value of coordinate +f number COORD for point number POINT is found in element +f POINTS(POINT,COORD). +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Notes: +* - An error is reported if the Region is unbounded. +* - If the coordinate system represented by the Region has been +* changed since it was first created, the returned axis values refer +* to the new (changed) coordinate system, rather than the original +* coordinate system. Note however that if the transformation from +* original to new coordinate system is non-linear, the shape within +* the new coordinate system may be distorted, and so may not match +* that implied by the name of the Region subclass (Circle, Box, etc). + +*-- +*/ + +/* Local Variables: */ + AstPointSet *pset; /* PointSet holding mesh/grid axis values */ + double **ptr; /* Pointer to mesh/grid axes values */ + double *p; /* Pointer to next input axis value */ + double *q; /* Pointer to next output axis value */ + int j; /* Axis index */ + int nc; /* No. of axes to copy */ + +/* Initialise */ + *npoint = 0; + +/* Check the inherited status. */ + if( !astOK ) return; + +/* Report an error if the Region is unbounded. */ + if( !astGetBounded( this ) ) { + if( astOK ) astError( AST__MBBNF, "astGetRegionMesh(%s): The supplied %s" + " is unbounded so no mesh can be created to cover " + "it.", status, astGetClass( this ), astGetClass( this ) ); + } else { + +/* Get the mesh or grid as required. If only the size of the mesh or grid + is required, get it in the base Frame as there is no need to spend the + extra time transforming it into the current Frame. */ + if( maxpoint == 0 ){ + if( surface ) { + pset = astRegBaseMesh( this ); + } else { + pset = astRegBaseGrid( this ); + } + } else { + if( surface ) { + pset = astRegMesh( this ); + } else { + pset = astRegGrid( this ); + } + } + +/* Return the number of points in the mesh or grid. */ + *npoint = astGetNpoint( pset ); + +/* Do nothing more unless a non-zero array size was supplied. */ + if( *npoint > 0 && maxpoint != 0 && astOK ) { + +/* Check the supplied array is large enough. */ + if( *npoint > maxpoint ) { + astError( AST__DIMIN, "astGetRegionMesh(%s): The supplied " + "array can hold up to %d points but the %s supplied " + "has %d points on its mesh (programming error).", + status, astGetClass( this ), maxpoint, astGetClass( this ), + *npoint ); + } + +/* Get the dimensionality of the PointSet, and get a pointer to the axis + values. */ + nc = astGetNcoord( pset ); + ptr = astGetPoints( pset ); + +/* Check pointers can be used safely. */ + if ( astOK ) { + +/* Check the supplied array has room for all the axes. */ + if( nc > maxcoord ) { + astError( AST__DIMIN, "astGetRegionMesh(%s): The supplied " + "array can hold up to %d axes but the %s supplied " + "has %d axes (programming error).", status, + astGetClass( this ), maxcoord, astGetClass( this ), nc ); + +/* If all is OK, copy the current Frame axis values into the supplied array. */ + } else { + +/* Loop round the axes to be copied. */ + for( j = 0; j < nc; j++ ) { + +/* Get points to the first element of the input and output arrays. */ + p = ptr[ j ]; + q = points + j*maxpoint; + +/* Copying the axis values. */ + (void) memcpy( q, p, sizeof( double )*( *npoint ) ); + } + } + } + } + +/* Free resources. */ + pset = astAnnul( pset ); + } +} + +static void GetRegionPoints( AstRegion *this, int maxpoint, int maxcoord, + int *npoint, double *points, int *status ){ +/* +*++ +* Name: +c astGetRegionPoints +f AST_GETREGIONPOINTS + +* Purpose: +* Returns the positions that define the given Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c void astGetRegionPoints( AstRegion *this, int maxpoint, int maxcoord, +c int *npoint, double *points ) +f CALL AST_GETREGIONPOINTS( THIS, MAXPOINT, MAXCOORD, NPOINT, POINTS, +f STATUS ) + +* Class Membership: +* Region method. + +* Description: +c This function +f This routine +* returns the axis values at the points that define the supplied +* Region. The particular meaning of these points will depend on the +* type of class supplied, as listed below under "Applicability:". + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +c maxpoint +f MAXPOINT = INTEGER (Given) +* If zero, the number of points needed to define the Region is +* returned in +c "*npoint", +f NPOINT, +* but no axis values are returned and all other parameters are ignored. +* If not zero, the supplied value should be the length of the +c second dimension of the "points" +f first dimension of the POINTS +* array. An error is reported if the number of points needed to define +* the Region exceeds this number. +c maxcoord +f MAXCOORD = INTEGER (Given) +* The length of the +c first dimension of the "points" array. +f second dimension of the POINTS array. +* An error is reported if the number of axes in the supplied Region +* exceeds this number. +c npoint +f NPOINT = INTEGER (Returned) +c A pointer to an integer in which to return the +f The +* number of points defining the Region. +c points +f POINTS( MAXPOINT, MAXCOORD ) = DOUBLE PRECISION (Returned) +c The address of the first element in a 2-dimensional array of +c shape "[maxcoord][maxpoint]", in which to return +c the coordinate values at the positions that define the Region. +c These are stored such that the value of coordinate number +c "coord" for point number "point" is found in element +c "points[coord][point]". +f An array in which to return the coordinates values at the +f positions that define the Region. These are stored such that the +f value of coordinate number COORD for point number POINT +f is found in element POINTS(POINT,COORD). +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Applicability: +* Region +* All Regions have this attribute. +* Box +* The first returned position is the Box centre, and the second is +* a Box corner. +* Circle +* The first returned position is the Circle centre, and the second is +* a point on the circumference. +* CmpRegion +* Returns a value of zero for +c "*npoint" +f NPOINT +* and leaves the supplied array contents unchanged. To find the +* points defining a CmpRegion, use this method on the component +* Regions, which can be accessed by invoking +c astDecompose +f AST_DECOMPOSE +* on the CmpRegion. +* Ellipse +* The first returned position is the Ellipse centre. The second is +* the end of one of the axes of the ellipse. The third is some +* other point on the circumference of the ellipse, distinct from +* the second point. +* Interval +* The first point corresponds to the lower bounds position, and +* the second point corresponds to the upper bounds position. These +* are reversed to indicate an extcluded interval rather than an +* included interval. See the Interval constructor for more +* information. +* NullRegion +* Returns a value of zero for +c "*npoint" +f NPOINT +* and leaves the supplied array contents unchanged. +* PointList +* The positions returned are those that were supplied when the +* PointList was constructed. +* Polygon +* The positions returned are the vertex positions that were supplied +* when the Polygon was constructed. +* Prism +* Returns a value of zero for +c "*npoint" +f NPOINT +* and leaves the supplied array contents unchanged. To find the +* points defining a Prism, use this method on the component +* Regions, which can be accessed by invoking +c astDecompose +f AST_DECOMPOSE +* on the CmpRegion. + +* Notes: +* - If the coordinate system represented by the Region has been +* changed since it was first created, the returned axis values refer +* to the new (changed) coordinate system, rather than the original +* coordinate system. Note however that if the transformation from +* original to new coordinate system is non-linear, the shape within +* the new coordinate system may be distorted, and so may not match +* that implied by the name of the Region subclass (Circle, Box, etc). + +*-- +*/ + +/* Local Variables: */ + AstPointSet *pset; /* PointSet holding PointList axis values */ + double **ptr; /* Pointer to axes values in the PointList */ + double *p; /* Pointer to next input axis value */ + double *q; /* Pointer to next output axis value */ + int j; /* Axis index */ + int nc; /* No. of axes to copy */ + +/* Initialise */ + *npoint = 0; + +/* Check the inherited status. */ + if( !astOK ) return; + +/* Return the number of points used to define the Region, if any. */ + *npoint = this->points ? astGetNpoint( this->points ) : 0; + +/* Do nothing more unless a non-zero array size was supplied. */ + if( *npoint > 0 && maxpoint != 0 ) { + +/* Transform the base Frame axis values into the current Frame. */ + pset = astTransform( this->frameset, this->points, 1, NULL ); + +/* Get the dimensionality of this PointList, and get a pointer to the axis + values. */ + nc = astGetNcoord( pset ); + ptr = astGetPoints( pset ); + +/* Check pointers can be used safely. */ + if ( astOK ) { + +/* Check the supplied array has room for all the axis values. */ + if( nc > maxcoord ) { + astError( AST__DIMIN, "astGetRegionPoints(%s): The supplied " + "array can hold up to %d axes but the %s supplied " + "has %d axes (programming error).", status, + astGetClass( this ), maxcoord, astGetClass( this ), nc ); + + } else if( *npoint > maxpoint ) { + astError( AST__DIMIN, "astGetRegionPoints(%s): The supplied " + "array can hold up to %d points but the %s supplied " + "requires %d points to describe it (programming " + "error).", status, astGetClass( this ), maxpoint, + astGetClass( this ), *npoint ); + +/* If all is OK, copy the transformed axis values into the supplied array. */ + } else { + +/* Loop round the axes to be copied. */ + for( j = 0; j < nc; j++ ) { + +/* Get points to the first element of the input and output arrays. */ + p = ptr[ j ]; + q = points + j*maxpoint; + +/* Copying the axis values. */ + (void) memcpy( q, p, sizeof( double )*( *npoint ) ); + } + } + } + +/* Free resources. */ + pset = astAnnul( pset ); + + } +} + +static void RegOverlay( AstRegion *this, AstRegion *that, int unc, int *status ){ +/* +*+ +* Name: +* astRegOverlay + +* Purpose: +* Copy properties from one Region to another. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astRegOverlay( AstRegion *this, AstRegion *that, int unc ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function copies selected properties from "that" to "this". +* It is intended to be called by sub-classes which need to create a +* similar copy of an existing Region. For instance, subclass +* implementations of the Simplify method will usually use this +* function to ensure that the simplified Region loooks like the original +* Region. + +* Parameters: +* this +* Pointer to the new Region. +* that +* Pointer to the old Region. +* unc +* If non-zero, any uncertainty in "this" is cleared if "that" has +* no uncertainty. If zero, any uncertainty in "this" is left +* unchanged. +*- +*/ + +/* Check the inherited status. */ + if( !astOK ) return; + +/* Copy the required attribute values. */ + this->negated = that->negated; + this->closed = that->closed; + this->regionfs = that->regionfs; + this->adaptive = that->adaptive; + +/* Clear things that depend on the number of axes. */ + if( astGetNaxes( this ) == astGetNaxes( that ) ) { + if( astTestMeshSize( that ) ) astSetMeshSize( this, astGetMeshSize( that ) ); + if( astTestFillFactor( that ) ) astSetFillFactor( this, astGetFillFactor( that ) ); + } else { + astClearMeshSize( this ); + astClearFillFactor( this ); + } + +/* If required, clear uncertainty in "this" if "that" has no uncertainty. */ + if( unc && !astTestUnc( that ) ) astClearUnc( this ); + +} + +static void RegSetAttrib( AstRegion *this, const char *asetting, + char **base_setting, int *status ) { +/* +*+ +* Name: +* astRegSetAttrib + +* Purpose: +* Set an attribute value for a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astRegSetAttrib( AstRegion *this, const char *asetting, +* char **base_setting ) + +* Class Membership: +* Region virtual function + +* Description: +* This function assigns an attribute value to both the base and +* current Frame in the FrameSet encapsulated within a Region, without +* remapping either Frame. +* +* No error is reported if the attribute is not recognised by the base +* Frame. + +* Parameters: +* this +* Pointer to the Region. +* asetting +* Pointer to a null terminated attribute setting string. The supplied +* string will be interpreted using the public interpretation +* implemented by astSetAttrib. This can be different to the +* interpretation of the protected accessor functions. For instance, +* the public interpretation of an unqualified floating point value for +* the Epoch attribute is to interpet the value as a gregorian year, +* but the protected interpretation is to interpret the value as an +* MJD. +* base_setting +* Address of a location at which to return a pointer to the null +* terminated attribute setting string which was applied to the +* base Frame of the encapsulated FrameSet. This may differ from +* the supplied setting if the supplied setting contains an axis +* index and the current->base Mapping in the FrameSet produces an +* axis permutation. The returned pointer should be freed using +* astFree when no longer needed. A NULL pointer may be supplied in +* which case no pointer is returned. +*- +*/ + +/* Local Variables: */ + AstFrame *frm; + AstMapping *junkmap; + AstMapping *map; + AstRegion *unc; + char *setting; + char *bsetting; + char buf1[ 100 ]; + int *outs; + int axis; + int baxis; + int i; + int len; + int nc; + int rep; + int value; + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Produce a lower case version of the setting string */ + nc = strlen( asetting ); + setting = astMalloc( nc + 1 ); + for( i = 0; i < nc; i++ ) setting[ i ] = tolower( asetting[ i ] ); + setting[ nc ] = 0; + +/* Apply the setting to the current Frame in the encapsulated FrameSet. + Use the protected astSetAttrib method which does not cause the Frame + to be remapped within the FrameSet. */ + frm = astGetFrame( this->frameset, AST__CURRENT ); + astSetAttrib( frm, setting ); + frm = astAnnul( frm ); + +/* Indicate that we should use the supplied setting with the base Frame. */ + bsetting = NULL; + +/* If the attribute name contains an axis number, we need to create a new + attribute setting which refers to the corresponding base Frame axis + (since the base<->current Mapping may permute the axes). First parse the + supplied attribute setting to locate any axis index. */ + len = strlen( setting ); + if( nc = 0, ( 2 == astSscanf( setting, "%[^(](%d)= %n%*s %n", buf1, &axis, + &value, &nc ) ) && ( nc >= len ) ) { + +/* If found, convert the axis index from one-based to zero-based. */ + axis--; + +/* See if the specified current Frame axis is connected to one and only + one base Frame axis. If so, get the index of the base Frame axis. */ + map = astGetMapping( this->frameset, AST__CURRENT, AST__BASE ); + outs = astMapSplit( map, 1, &axis, &junkmap ); + if( junkmap && astGetNout( junkmap ) == 1 ) { + baxis = outs[ 0 ]; + +/* If the base Frame axis index is different to the current Frame axis + index, create a new setting string using the base Frame axis index. */ + if( baxis != axis ) { + bsetting = astMalloc( strlen( setting ) + 10 ); + if( bsetting ) { + sprintf( bsetting, "%s(%d)=%s", buf1, baxis + 1, setting + value ); + } + } + +/* If there is no one base Frame axis which corresponds to the supplied + current Frame axis, report an error. */ + } else if( astOK ) { + astError( AST__INTER, "astRegSetAttrib(%s): Unable to apply " + "attribute setting \"%s\" to the base Frame in the %s", status, + astGetClass( this ), setting, astGetClass( this ) ); + astError( AST__INTER, "There is no base Frame axis corresponding " + "to current Frame axis %d\n", status, axis + 1 ); + } + +/* Free resources */ + outs = astFree( outs ); + if( junkmap ) junkmap = astAnnul( junkmap ); + map = astAnnul( map ); + } + +/* Apply the appropriate attribute setting to the base Frame. This time + ensure that any error caused by the attribute setting is annulled. + Also apply it to any uncertainty Region (the current Frame of the + uncertainty Region is assumed to be equivalent to the base Frame of the + parent Region). */ + frm = astGetFrame( this->frameset, AST__BASE ); + if( frm ) { + rep = astReporting( 0 ); + astSetAttrib( frm, bsetting ? bsetting : setting ); + if( astTestUnc( this ) ) { + unc = astGetUncFrm( this, AST__BASE ); + astRegSetAttrib( unc, bsetting ? bsetting : setting, NULL ); + unc = astAnnul( unc ); + } + if( astStatus == AST__BADAT ) astClearStatus; + astReporting( rep ); + } + frm = astAnnul( frm ); + +/* If required return the modified base Frame setting. Otherwise, free it. */ + if( base_setting ) { + if( bsetting ) { + *base_setting = bsetting; + } else { + *base_setting = astStore( NULL, setting, strlen( setting ) + 1 ); + } + } else { + bsetting = astFree( bsetting ); + } + +/* Since the base Frame has been changed, any cached information calculated + on the basis of the base Frame properties may no longer be up to date. */ + astResetCache( this ); + +/* Free resources. */ + setting = astFree( setting ); + +} + +static AstMapping *RemoveRegions( AstMapping *this_mapping, int *status ) { +/* +* Name: +* RemoveRegions + +* Purpose: +* Remove any Regions from a Mapping. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstMapping *RemoveRegions( AstMapping *this, int *status ) + +* Class Membership: +* Region method (over-rides the astRemoveRegions method inherited +* from the Frame class). + +* Description: +* This function searches the supplied Mapping (which may be a +* compound Mapping such as a CmpMap) for any component Mappings +* that are instances of the AST Region class. It then creates a new +* Mapping from which all Regions have been removed. If a Region +* cannot simply be removed (for instance, if it is a component of a +* parallel CmpMap), then it is replaced with an equivalent UnitMap +* in the returned Mapping. +* +* The implementation provided by the Region class just returns the +* equivalent Frame. + +* Parameters: +* this +* Pointer to the original Region. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A pointer to the modified mapping. + +* Notes: +* - A NULL pointer value will be returned if this function is +* invoked with the AST error status set, or if it should fail for +* any reason. +*/ + +/* The Region class just returns a pointer to a deep copy of the Region's + equivalent Frame. */ + return astGetRegionFrame( (AstRegion *)this_mapping ); +} + +static void ReportPoints( AstMapping *this_mapping, int forward, + AstPointSet *in_points, AstPointSet *out_points, int *status ) { +/* +* Name: +* ReportPoints + +* Purpose: +* Report the effect of transforming a set of points using a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void ReportPoints( AstMapping *this, int forward, +* AstPointSet *in_points, AstPointSet *out_points, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astReportPoints +* method inherited from the Frame class). + +* Description: +* This function reports the coordinates of a set of points before +* and after being transformed by a Region, by writing them to +* standard output. + +* Parameters: +* this +* Pointer to the Region. +* forward +* A non-zero value indicates that the Region's forward +* coordinate transformation has been applied, while a zero +* value indicates the inverse transformation. +* in_points +* Pointer to a PointSet which is associated with the +* coordinates of a set of points before the Region was +* applied. +* out_points +* Pointer to a PointSet which is associated with the +* coordinates of the same set of points after the Region has +* been applied. +* status +* Pointer to the inherited status variable. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_mapping; + +/* Obtain a pointer to the Region's current Frame and invoke its + astReportPoints method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astReportPoints( (AstMapping *) fr, forward, in_points, out_points ); + fr = astAnnul( fr ); + +} + +static void ResetCache( AstRegion *this, int *status ){ +/* +*+ +* Name: +* astResetCache + +* Purpose: +* Clear cached information within the supplied Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astResetCache( AstRegion *this ) + +* Class Membership: +* Region virtual function + +* Description: +* This function clears cached information from the supplied Region +* structure. + +* Parameters: +* this +* Pointer to the Region. +*- +*/ + if( this ) { + if( this->basemesh ) this->basemesh = astAnnul( this->basemesh ); + if( this->basegrid ) this->basegrid = astAnnul( this->basegrid ); + if( this->negation ) this->negation = astAnnul( this->negation ); + } +} + + +static void Resolve( AstFrame *this_frame, const double point1[], + const double point2[], const double point3[], + double point4[], double *d1, double *d2, int *status ){ +/* +* Name: +* Resolve + +* Purpose: +* Resolve a vector into two orthogonal components + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void Resolve( AstFrame *this, const double point1[], +* const double point2[], const double point3[], +* double point4[], double *d1, double *d2, int *status ); + +* Class Membership: +* Region member function (over-rides the protected astResolve +* method inherited from the Frame class). + +* Description: +* This function resolves a vector into two perpendicular components. +* The vector from point 1 to point 2 is used as the basis vector. +* The vector from point 1 to point 3 is resolved into components +* parallel and perpendicular to this basis vector. The lengths of the +* two components are returned, together with the position of closest +* aproach of the basis vector to point 3. + +* Parameters: +* this +* Pointer to the Frame. +* point1 +* An array of double, with one element for each Frame axis +* (Naxes attribute). This marks the start of the basis vector, +* and of the vector to be resolved. +* point2 +* An array of double, with one element for each Frame axis +* (Naxes attribute). This marks the end of the basis vector. +* point3 +* An array of double, with one element for each Frame axis +* (Naxes attribute). This marks the end of the vector to be +* resolved. +* point4 +* An array of double, with one element for each Frame axis +* in which the coordinates of the point of closest approach of the +* basis vector to point 3 will be returned. +* d1 +* The address of a location at which to return the distance from +* point 1 to point 4 (that is, the length of the component parallel +* to the basis vector). Positive values are in the same sense as +* movement from point 1 to point 2. +* d2 +* The address of a location at which to return the distance from +* point 4 to point 3 (that is, the length of the component +* perpendicular to the basis vector). The value is always positive. +* status +* Pointer to the inherited status variable. + +* Notes: +* - Each vector used in this function is the path of +* shortest distance between two points, as defined by the +* astDistance function. +* - This function will return "bad" coordinate values (AST__BAD) +* if any of the input coordinates has this value, or if the required +* output values are undefined. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke this + Frame's astResolve method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astResolve( fr, point1, point2, point3, point4, d1, d2 ); + fr = astAnnul( fr ); + +} + +static AstPointSet *ResolvePoints( AstFrame *this_frame, const double point1[], + const double point2[], AstPointSet *in, + AstPointSet *out, int *status ) { +/* +* Name: +* ResolvePoints + +* Purpose: +* Resolve a set of vectors into orthogonal components + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstPointSet *ResolvePoints( AstFrame *this, const double point1[], +* const double point2[], AstPointSet *in, +* AstPointSet *out ) + +* Class Membership: +* Region member function (over-rides the astResolvePoints method +* inherited from the Frame class). + +* Description: +* This function takes a Frame and a set of vectors encapsulated +* in a PointSet, and resolves each one into two orthogonal components, +* returning these two components in another PointSet. +* +* This is exactly the same as the public astResolve method, except +* that this method allows many vectors to be processed in a single call, +* thus reducing the computational cost of overheads of many +* individual calls to astResolve. + +* Parameters: +* this +* Pointer to the Frame. +* point1 +* An array of double, with one element for each Frame axis +* (Naxes attribute). This marks the start of the basis vector, +* and of the vectors to be resolved. +* point2 +* An array of double, with one element for each Frame axis +* (Naxes attribute). This marks the end of the basis vector. +* in +* Pointer to the PointSet holding the ends of the vectors to be +* resolved. +* out +* Pointer to a PointSet which will hold the length of the two +* resolved components. A NULL value may also be given, in which +* case a new PointSet will be created by this function. + +* Returned Value: +* Pointer to the output (possibly new) PointSet. The first axis will +* hold the lengths of the vector components parallel to the basis vector. +* These values will be signed (positive values are in the same sense as +* movement from point 1 to point 2. The second axis will hold the lengths +* of the vector components perpendicular to the basis vector. These +* values will always be positive. + +* Notes: +* - The number of coordinate values per point in the input +* PointSet must match the number of axes in the supplied Frame. +* - If an output PointSet is supplied, it must have space for +* sufficient number of points and 2 coordinate values per point. +* - A null pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstPointSet *result; /* Pointer to output PointSet */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Initialise. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke this + Frame's astResolve method. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astResolvePoints( fr, point1, point2, in, out ); + fr = astAnnul( fr ); + +/* Return a pointer to the output PointSet. */ + return result; + +} + +static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { +/* +* Name: +* SetAttrib + +* Purpose: +* Set an attribute value for a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void SetAttrib( AstObject *this, const char *setting, int *status ) + +* Class Membership: +* Region member function (extends the astSetAttrib method +* inherited from the Frame class). + +* Description: +* This function assigns an attribute value for a Region, the +* attribute and its value being specified by means of a string of +* the form: +* +* "attribute= value " +* +* Here, "attribute" specifies the attribute name and should be in +* lower case with no white space present. The value to the right +* of the "=" should be a suitable textual representation of the +* value to be assigned and this will be interpreted according to +* the attribute's data type. White space surrounding the value is +* only significant for string attributes. + +* Parameters: +* this +* Pointer to the Region. +* setting +* Pointer to a null terminated string specifying the new +* attribute value. +* status +* Pointer to the inherited status variable. + +* Notes: +* - This protected method is intended to be invoked by the Object +* astSet method and makes additional attributes accessible to it. +*/ + +/* Local Variables: */ + AstRegion *this; /* Pointer to the Region structure */ + double dval; /* Floating point attribute value */ + int ival; /* Integer attribute value */ + int id; /* Offset of ID string */ + int len; /* Length of setting string */ + int nc; /* Number of characters read by astSscanf */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_object; + +/* Obtain the length of the setting string. */ + len = strlen( setting ); + +/* Test for each recognised attribute in turn, using "astSscanf" to parse the + setting string and extract the attribute value (or an offset to it in the + case of string values). In each case, use the value set in "nc" to check + that the entire string was matched. Once a value has been obtained, use the + appropriate method to set it. */ + +/* We first handle attributes that apply to the Region as a whole + (rather than to the encapsulated Frame). */ + +/* Negated */ +/* ------- */ + if ( nc = 0, + ( 1 == astSscanf( setting, "negated= %d %n", &ival, &nc ) ) + && ( nc >= len ) ) { + astSetNegated( this, ival ); + +/* Closed */ +/*------- */ + } else if ( nc = 0, + ( 1 == astSscanf( setting, "closed= %d %n", &ival, &nc ) ) + && ( nc >= len ) ) { + astSetClosed( this, ival ); + +/* FillFactor */ +/* ---------- */ + } else if ( nc = 0, + ( 1 == astSscanf( setting, "fillfactor= %lg %n", &dval, &nc ) ) + && ( nc >= len ) ) { + astSetFillFactor( this, dval ); + +/* MeshSize */ +/* -------- */ + } else if ( nc = 0, + ( 1 == astSscanf( setting, "meshsize= %d %n", &ival, &nc ) ) + && ( nc >= len ) ) { + astSetMeshSize( this, ival ); + +/* Adaptive */ +/* -------- */ + } else if ( nc = 0, + ( 1 == astSscanf( setting, "adaptive= %d %n", &ival, &nc ) ) + && ( nc >= len ) ) { + astSetAdaptive( this, ival ); + +/* Now do attributes inherited from parent classes. We do these here to + avoid the settings being passed on to the encapsulated FrameSet below. */ + +/* ID. */ +/* --- */ + } else if ( nc = 0, ( 0 == astSscanf( setting, "id=%n%*[^\n]%n", &id, &nc ) ) + && ( nc >= len ) ) { + astSetID( this, setting + id ); + +/* Ident. */ +/* ------ */ + } else if ( nc = 0, ( 0 == astSscanf( setting, "ident=%n%*[^\n]%n", &id, &nc ) ) + && ( nc >= len ) ) { + astSetIdent( this, setting + id ); + +/* Invert. */ +/* ------- */ + } else if ( nc = 0, + ( 1 == astSscanf( setting, "invert= %d %n", &ival, &nc ) ) + && ( nc >= len ) ) { + astSetInvert( this, ival ); + +/* Report. */ +/* ------- */ + } else if ( nc = 0, + ( 1 == astSscanf( setting, "report= %d %n", &ival, &nc ) ) + && ( nc >= len ) ) { + astSetReport( this, ival ); + +/* Define macros to see if the setting string matches any of the + read-only attributes of this class. */ +#define MATCH(attrib) \ + ( nc = 0, ( 0 == astSscanf( setting, attrib "=%*[^\n]%n", &nc ) ) && \ + ( nc >= len ) ) + +#define AXISMATCH(attrib) \ + ( nc = 0, ( 0 == astSscanf( setting, attrib "(%*d)=%*[^\n]%n", &nc ) ) && \ + ( nc >= len ) ) + +/* If the attribute was not recognised, use this macro to report an error + if a read-only attribute has been specified. */ + } else if ( MATCH( "class" ) || + MATCH( "nin" ) || + MATCH( "nobject" ) || + MATCH( "bounded" ) || + MATCH( "nout" ) || + MATCH( "refcount" ) || + MATCH( "tranforward" ) || + MATCH( "traninverse" ) ) { + astError( AST__NOWRT, "astSet: The setting \"%s\" is invalid for a %s.", status, + setting, astGetClass( this ) ); + astError( AST__NOWRT, "This is a read-only attribute." , status); + +/* Pass unrecognised attributes on to the Region's encapsulated FrameSet for + further interpretation. Do not pass on FrameSet attributes since we + pretend to the outside world that the encapsulated FrameSet is actually a + Frame. */ + } else if ( !MATCH( "base" ) && + !MATCH( "current" ) && + !MATCH( "nframe" ) ) { + +/* If the Region is to adapt to coordinate system chanmges, use the public + astSet method so that the current Frame in the encapsulated FrameSet will + be re-mapped if the attribute changes require it. */ + if( astGetAdaptive( this ) ) { + astSet( this->frameset, setting, status ); + +/* If the Region is not to adapt to coordinate system chanmges, use the + astRegSetAttrib method which assigns the attribute setting to both + current and base Frames in the FrameSet without causing any remapping to + be performed. */ + } else { + astRegSetAttrib( this, setting, NULL ); + } + } + +/* Undefine macros local to this function. */ +#undef MATCH +} + +static void SetAxis( AstFrame *this_frame, int axis, AstAxis *newaxis, int *status ) { +/* +* Name: +* SetAxis + +* Purpose: +* Set a new Axis for a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void SetAxis( AstFrame *this, int axis, AstAxis *newaxis, int *status ) + +* Class Membership: +* Region member function (over-rides the astSetAxis method +* inherited from the Frame class). + +* Description: +* This function allows a new Axis object to be associated with one +* of the axes of the current Frame in a Region, replacing the +* previous one. Each Axis object contains a description of the +* quantity represented along one of the Frame's axes, so this +* function allows this description to be exchanged for another +* one. + +* Parameters: +* this +* Pointer to the Region. +* axis +* The index (zero-based) of the axis whose associated Axis +* object is to be replaced. +* newaxis +* Pointer to the new Axis object. +* status +* Pointer to the inherited status variable. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index supplied. */ + (void) astValidateAxis( this, axis, 1, "astSetAxis" ); + +/* Obtain a pointer to the Region's current Frame and invoke this + Frame's astSetAxis method to assign the new Axis object. Annul the + Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astSetAxis( fr, axis, newaxis ); + fr = astAnnul( fr ); +} + +static void SetRegFS( AstRegion *this, AstFrame *frm, int *status ) { +/* +*+ +* Name: +* astSetRegFS + +* Purpose: +* Stores a new FrameSet in a Region + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* void astSetRegFS( AstRegion *this, AstFrame *frm ) + +* Class Membership: +* Region virtual function. + +* Description: +* This function creates a new FrameSet and stores it in the supplied +* Region. The new FrameSet contains two copies of the supplied +* Frame, connected by a UnitMap. + +* Parameters: +* this +* Pointer to the Region. +* frm +* The Frame to use. +*- +*/ + +/* Local Variables: */ + AstFrame *f1; /* Copy of supplied Frame */ + AstFrame *f2; /* Copy of supplied Frame */ + AstFrameSet *fs; /* New FrameSet */ + AstRegion *unc; /* Uncertainty Region */ + AstUnitMap *um; /* UnitMap connecting base anc current Frames */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Take a copy of the supplied Frame. */ + f1 = astCopy( frm ); + +/* Create the new FrameSet. First take another copy of the supplied Frame + so that modifications using the supplied pointer will not affect the new + FrameSet. We create two copies (rather than 1) because the base and + current Frames must be independant objects - otherwise attribute changes + done to one will also appear in the other. Then construct the FrameSet + containing the two Frame copies connected by a UnitMap. */ + f2 = astCopy( f1 ); + fs = astFrameSet( f1, "", status ); + um = astUnitMap( astGetNaxes( f1 ), "", status ); + astAddFrame( fs, AST__BASE, um, f2 ); + um = astAnnul( um ); + f2 = astAnnul( f2 ); + +/* Annul any existing FrameSet */ + if( this->frameset ) (void) astAnnul( this->frameset ); + +/* Use the new FrameSet */ + this->frameset = fs; + +/* If any uncertainty Region has a zero value for its RegionFS attribute, + it will currently contain a dummy FrameSet rather than the correct + FrameSet. The correct FrameSet has copies of the base Frame of the new + Region as both its current and base Frames, and these are connected by + a UnitMap (this is equivalent to a FrameSet containing a single Frame). */ + if( astTestUnc( this ) ) { + unc = astGetUncFrm( this, AST__BASE ); + if( unc && !astGetRegionFS( unc ) ) astSetRegFS( unc, f1 ); + unc = astAnnul( unc ); + } + +/* Free remaining resourvces */ + f1 = astAnnul( f1 ); + +} + +static void SetUnc( AstRegion *this, AstRegion *unc, int *status ){ +/* +*++ +* Name: +c astSetUnc +f AST_SETUNC + +* Purpose: +* Store uncertainty information in a Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c void astSetUnc( AstRegion *this, AstRegion *unc ) +f CALL AST_SETUNC( THIS, UNC, STATUS ) + +* Class Membership: +* Region method. + +* Description: +* Each Region (of any class) can have an "uncertainty" which specifies +* the uncertainties associated with the boundary of the Region. This +* information is supplied in the form of a second Region. The uncertainty +* in any point on the boundary of a Region is found by shifting the +* associated "uncertainty" Region so that it is centred at the boundary +* point being considered. The area covered by the shifted uncertainty +* Region then represents the uncertainty in the boundary position. +* The uncertainty is assumed to be the same for all points. +* +* The uncertainty is usually specified when the Region is created, but +* this +c function +f routine +* allows it to be changed at any time. + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region which is to be assigned a new uncertainty. +c unc +f UNC = INTEGER (Given) +* Pointer to the new uncertainty Region. This must be of a class for +* which all instances are centro-symetric (e.g. Box, Circle, Ellipse, +* etc.) or be a Prism containing centro-symetric component Regions. +* A deep copy of the supplied Region will be taken, so subsequent +* changes to the uncertainty Region using the supplied pointer will +* have no effect on the Region +c "this". +f THIS. +f STATUS = INTEGER (Given and Returned) +f The global status. + +*-- +*/ + +/* Local Variables: */ + AstFrame *frm; /* Current Frame from FrameSet */ + AstFrameSet *fs2; /* FrameSet from "unc" current Frame to "this" base Frame */ + AstFrameSet *fs; /* FrameSet in "this" supplied Region */ + AstMapping *map2; /* Base->current Mapping from FrameSet */ + AstMapping *map; /* Base->current Mapping from FrameSet */ + AstMapping *smap; /* Simplified base->current Mapping */ + double *cen0; /* Pointer to array holding original centre */ + double **ptr_reg; /* Pointer to axis values for Region's Pointset */ + int changed; /* Has the uncertainty been changed? */ + +/* Check the inherited status. */ + if( !astOK ) return; + +/* Annul any existing uncertainty Region. */ + if( this->unc ) { + this->unc = astIsAObject( this->unc ) ? + astAnnul( this->unc ) : NULL; + changed = 1; + } else { + changed = 0; + } + +/* Check an uncertainty Region was supplied, and is of a usable class + (i.e. a class which can be re-centred). */ + cen0 = unc ? astRegCentre( unc, NULL, NULL, 0, 0 ) : NULL; + if( cen0 ) { + cen0 = astFree( cen0 ); + +/* Map it into the same Frame as that represented by the base Frame in + the supplied Region. */ + fs = this->frameset; + astInvert( fs ); + fs2 = Conv( unc->frameset, fs, status ); + astInvert( fs ); + + if( fs2 ) { + map = astGetMapping( fs2, AST__BASE, AST__CURRENT ); + frm = astGetFrame( fs2, AST__CURRENT ); + this->unc = astMapRegion( unc, map, frm ); + if( this->unc ) { + +/* Ensure the Region is bounded. We know that negating an unbounded + Region will make it bounded because we know that the Region consists of + Circles, Boxes and/or Ellipses, all of which have this property. */ + if( !astGetBounded( this->unc ) ) astNegate( this->unc ); + +/* If the base Frame in the uncertainty Region is the same as the base + Frame in the Region being dumped, then we do no need to include the + FrameSet in the dump of the uncertainty Region. Since the current + Frame in the uncertainty Region always corresponds to the base Frame of + its parent Region, we only need to check if the base->current Mapping + in the uncertainty Region's FrameSet is a UnitMap or not (after + simplification). If it is, set the RegionFS attribute of the uncertainty + Region to zero (i.e. false). This will cause the FrameSet to be omitted + from the Dump. */ + map2 = astGetMapping( this->unc->frameset, AST__BASE, AST__CURRENT ); + smap = astSimplify( map2 ); + if( astIsAUnitMap( smap ) ) astSetRegionFS( this->unc, 0 ); + +/* Re-centre the uncertainty Region at the first position in the PointSet + associated with the Region structure (if any). */ + if( this->points ) { + ptr_reg = astGetPoints( this->points ); + astRegCentre( this->unc, NULL, ptr_reg, 0, AST__CURRENT ); + } + +/* Set a flag indicating that the uncertainty in the Region has changed. */ + changed = 1; + +/* Free resources */ + map2 = astAnnul( map2 ); + smap = astAnnul( smap ); + } + frm = astAnnul( frm ); + fs2 = astAnnul( fs2 ); + map = astAnnul( map ); + +/* Report error if conversion between Frames is not possible. */ + } else if( astOK ) { + astError( AST__BADIN, "astSetUnc(%s): Bad %d dimensional " + "uncertainty Frame (%s %s) supplied.", status, astGetClass(this), + astGetNaxes(unc), astGetDomain(unc), astGetTitle(unc) ); + astError( AST__NCPIN, "Cannot convert it to the Frame of the " + "new %s.", status, astGetClass( this ) ); + } + +/* Report an error if it is not of a usable class. */ + } else if( unc && astOK ){ + astError( AST__BADIN, "astSetUnc(%s): Bad uncertainty shape " + "(%s) supplied.", status, astGetClass( this ), astGetClass(unc) ); + astError( AST__NCPIN, "The uncertainty Region must be an instance of " + "a centro-symetric subclass of Region (e.g. Box, Circle, " + "Ellipse, etc)." , status); + } + +/* If the uncertainty in the Region has changed, indicate that any cached + information in the Region is now out of date. */ + if( changed ) astResetCache( this ); + +} + +static void ShowMesh( AstRegion *this, int format, const char *ttl, int *status ){ +/* +*++ +* Name: +c astShowMesh +f AST_SHOWMESH + +* Purpose: +* Display a mesh of points covering the surface of a Region. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c void astShowMesh( AstRegion *this, int format, const char *ttl ) +f CALL AST_SHOWMESH( THIS, FORMAT, TTL, STATUS ) + +* Class Membership: +* Region method. + +* Description: +c This function +f This routine +* writes a table to standard output containing the axis values at a +* mesh of points covering the surface of the supplied Region. Each row +* of output contains a tab-separated list of axis values, one for +* each axis in the Frame encapsulated by the Region. The number of +* points in the mesh is determined by the MeshSize attribute. +* +* The table is preceded by a given title string, and followed by a +* single line containing the word "ENDMESH". + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +c format +f FORMAT = LOGICAL (Given) +* A boolean value indicating if the displayed axis values should +* be formatted according to the Format attribute associated with +* the Frame's axis. Otherwise, they are displayed as simple +* floating point values. +c ttl +f TTL = CHARACTER * ( * ) (Given) +* A title to display before displaying the first position. +f STATUS = INTEGER (Given and Returned) +f The global status. + +*-- +*/ + +/* Local Variables: */ + AstPointSet *ps; /* PointSet holding mesh */ + char *buffer = NULL; /* Buffer for line output text */ + char buf[ 40 ]; /* Buffer for floating poitn value */ + double **ptr; /* Pointers to the mesh data */ + int i; /* Axis index */ + int j; /* Position index */ + int nax; /* Number of axes */ + int nc; /* Number of characters in buffer */ + int np; /* Number of axis values per position */ + +/* Check the inherited status. */ + if( !astOK ) return; + +/* Get a PointSet holding the mesh */ + ps = astRegMesh( this ); + if( ps ) { + +/* Get the number of axis values per position, and the number of positions. */ + nax = astGetNcoord( ps ); + np = astGetNpoint( ps ); + +/* Get a pointer to the mesh data, and check it can be used. */ + ptr = astGetPoints( ps ); + if( ptr ) { + +/* Display the title. */ + if( ttl ) printf( "\n%s\n\n", ttl ); + +/* Loop round all positions. */ + for( j = 0; j < np; j++ ) { + +/* Reset the current buffer length to zero. */ + nc = 0; + +/* Loop round all axes */ + for( i = 0; i < nax; i++ ){ + +/* If the axis value is bad, append "<bad> in the end of the output buffer. */ + if( ptr[ i ][ j ] == AST__BAD ){ + buffer = astAppendString( buffer, &nc, "<bad>" ); + +/* Otherwise, if required, append the formatted value to the end of the + buffer. */ + } else if( format ){ + buffer = astAppendString( buffer, &nc, + astFormat( this, i, ptr[ i ][ j ] ) ); + +/* Otherwise, append the floating point value to the end of the buffer. */ + } else { + sprintf( buf, "%g", ptr[ i ][ j ] ); + buffer = astAppendString( buffer, &nc, buf ); + } +/* Add a separating tab to the end of the buffer. */ + buffer = astAppendString( buffer, &nc, "\t" ); + } + +/* Display the line buffer. */ + printf( "%s\n", buffer ); + } + } + +/* Print out a marker for th eend of the list. */ + printf( "ENDMESH\n\n" ); + +/* Release resources. */ + ps = astAnnul( ps ); + buffer = astFree( buffer ); + } +} + +static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { +/* +* Name: +* Simplify + +* Purpose: +* Simplify the Mapping represented by a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstMapping *Simplify( AstMapping *this, int *status ) + +* Class Membership: +* Region method (over-rides the astSimplify method inherited +* from the Frame class). + +* Description: +* This function simplifies the encapsulated FrameSet and any +* uncertainty Region in the supplied Region. This is different to +* the Simplify method in the parent Frame class which always returns +* a UnitMap. + +* Parameters: +* this +* Pointer to the original Region. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A pointer to the simplified Region. A cloned pointer to the +* supplied Region will be returned if no simplication could be +* performed. + +* Notes: +* - This implementation just simplifies the encapsulated FrameSet +* and uncertainty Region. Sub-classes should usually provide their own +* implementation which invokes this implemetation, and then continues to +* check for further simplifications (such as fitting a new region to the +* current Frame). +* - A NULL pointer value will be returned if this function is +* invoked with the AST error status set, or if it should fail for +* any reason. +*/ + +/* Local Variables: */ + AstFrame *bfrm; /* Pointer to "this" baseFrame */ + AstFrameSet *fs; /* Pointer to encapsulated FrameSet */ + AstMapping *map; /* Base->current Mapping for "this" */ + AstMapping *result; /* Result pointer to return */ + AstPointSet *pset1; /* Base Frame centre position */ + AstPointSet *pset2; /* Current Frame centre position */ + AstRegion *new; /* Pointer to simplified Region */ + AstRegion *sunc; /* Simplified uncertainty Region */ + AstRegion *this; /* Pointer to original Region structure */ + AstRegion *unc; /* Original uncertainty Region */ + double **ptr1; /* Pointer to axis values in "pset1" */ + double *cen; /* Original centre of uncertainty Region */ + double *lbnd; /* Lower bounds of "this" bounding box */ + double *orig_cen; /* Original centre for uncertainty Region */ + double *s1_lbnd; /* Lower bounds of "unc" when centred at lbnd */ + double *s1_ubnd; /* Upper bounds of "unc" when centred at lbnd */ + double *s2_lbnd; /* Lower bounds of "unc" when centred at ubnd */ + double *s2_ubnd; /* Upper bounds of "unc" when centred at ubnd */ + double *ubnd; /* Upper bounds of "this" bounding box */ + double delta; /* Half width of test box */ + double w1; /* Width of "s1" bounding box */ + double w2; /* Width of "s2" bounding box */ + int ic; /* Axis index */ + int naxb; /* No. of base Frame axes in "this" */ + int nin; /* Number of base Frame axes in "this" */ + int nout; /* Number of current Frame axes in "this" */ + int ok; /* Can we use the simplified uncertainty? */ + int simpler; /* Has some simplication taken place? */ + +/* Initialise. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_mapping; + +/* Take a deep copy of the supplied Region. This is so that the returned + pointer will have a diferent value to the supplied pointer if any + simplication takes place. */ + new = astCopy( this ); + +/* Simplify the encapsulated FrameSet, and note if any simplification took + place. */ + fs = astSimplify( new->frameset ); + simpler = ( fs != new->frameset ); + +/* If so, annull the existing FrameSet and use the simpler FrameSet. */ + if( simpler ) { + (void) astAnnul( new->frameset ); + new->frameset = astClone( fs ); + } + fs = astAnnul( fs ); + +/* If the Region has default uncertainty, we simplify the uncertainty + Region simply by deleting it. It will be regenerated when needed, + using the simplified Region. */ + if( new->defunc ) new->defunc = astAnnul( new->defunc ); + +/* If the Region's uncertainty was supplied explicitly, try simplifying + the unncertainty Region. */ + if( astTestUnc( new ) ){ + +/* Obtain the Region's uncertainty. */ + unc = astGetUncFrm( new, AST__BASE ); + +/* Get the base->current Mapping from "this". */ + map = astGetMapping( this->frameset, AST__BASE, AST__CURRENT ); + +/* If it has different numbers of inputs and outputs (e.g. a PermMap used + to take a slice through a Region), we need to ensure that the + uncertainty Region is centred on the slice. */ + nin = astGetNin( map ); + nout = astGetNout( map ); + if( nin != nout ) { + +/* Get the current centre of the uncertainty Region in its current Frame + (the same as the base Frame of "this"). */ + cen = astRegCentre( unc, NULL, NULL, 0, AST__CURRENT ); + +/* Store it in a PointSet so it can be transformed. */ + pset1 = astPointSet( 1, nin, "", status ); + ptr1 = astGetPoints( pset1 ); + if( astOK ) for( ic = 0; ic < nin; ic++ ) ptr1[ ic ][ 0 ] = cen[ ic ]; + +/* Transform into the curent Frame of "this", and then back into the base + Frame. */ + pset2 = astTransform( map, pset1, 1, NULL ); + (void) astTransform( map, pset2, 0, pset1 ); + +/* Re-centre the uncertainty Region at this position. */ + astRegCentre( unc, NULL, ptr1, 0, AST__CURRENT ); + +/* Free resources. */ + cen = astFree( cen ); + pset1 = astAnnul( pset1 ); + pset2 = astAnnul( pset2 ); + } + +/* Free resources. */ + map = astAnnul( map ); + +/* Try simplifying the uncertainty. Only proceed if the uncertainty can + be simplified. */ + sunc = astSimplify( unc ); + if( sunc != unc ) { + +/* If the uncertainty can be simplified it means that the base->current + Mapping in the uncertainty Region is sufficiently linear to allow the + uncertainty shape to retain its form when transformed from the base to + the current Frane. But this has only been tested at the current centre + position in the uncertainty Region. The uncertainty Region should + describe the whole of "this" Region, and so we need to check that the + simplified uncertainty does not change as we move it around within "this" + Region. To do this, we re-centre the uncertainty region at opposite + corners of a large test box, and then we find the bounding box of the + re-centred uncertainty Region. If this uncertainty bounding box changes + from corner to corner of the test box, then we do not simplify the + uncertainty Region. If "this" is bounded, we use the bounding box of + "this" as the test box. Otherwise we use a box 100 times the size of the + uncertainty Region. */ + +/* Note the original base Frame centre of the simplified uncertainty Region. */ + orig_cen = astRegCentre( sunc, NULL, NULL, 0, AST__BASE ); + +/* Allocate memory to hold the bounds of the test box. */ + naxb = astGetNin( this->frameset ); + lbnd = astMalloc( sizeof( double )*(size_t)naxb ); + ubnd = astMalloc( sizeof( double )*(size_t)naxb ); + +/* If possible, get the base Frame bounding box of "this" and use it as + the test box. */ + if( astGetBounded( this ) ) { + astRegBaseBox( this, lbnd, ubnd ); + +/* Otherwise, store the bounds of a box which is 100 times the size of + the uncertainty region, centred on the current centre of the uncertainty + region (we know all uncertainty regions are bounded). */ + } else { + astGetRegionBounds( sunc, lbnd, ubnd ); + for( ic = 0; ic < naxb; ic++ ) { + delta = 0.5*fabs( ubnd[ ic ] - lbnd[ ic ] ); + lbnd[ ic ] = orig_cen[ ic ] - delta; + ubnd[ ic ] = orig_cen[ ic ] + delta; + } + } + +/* Re-centre it at the lower bounds of the test box. This is in the base Frame + of "this" which is the same as the current Frame of "sunc". */ + astRegCentre( sunc, lbnd, NULL, 0, AST__CURRENT ); + +/* Get the bounding box of the re-centred uncertainty Region, within its + current Frame, which is the same as the base Frame of "this". */ + s1_lbnd = astMalloc( sizeof( double )*(size_t)naxb ); + s1_ubnd = astMalloc( sizeof( double )*(size_t)naxb ); + astGetRegionBounds( sunc, s1_lbnd, s1_ubnd ); + +/* Now re-centre the uncertainty Region at the upper bounds of the test + box. */ + astRegCentre( sunc, ubnd, NULL, 0, AST__CURRENT ); + +/* Get the bounding box of the re-centred uncertainty Region. */ + s2_lbnd = astMalloc( sizeof( double )*(size_t)naxb ); + s2_ubnd = astMalloc( sizeof( double )*(size_t)naxb ); + astGetRegionBounds( sunc, s2_lbnd, s2_ubnd ); + +/* Get a pointer to the base Frame of "this". */ + bfrm = astGetFrame( this->frameset, AST__BASE ); + +/* The "ok" flag is initialised to indicate that the simplified uncertainty + Region should not be used. */ + ok = 0; + +/* Check pointers can be referenced safely */ + if( astOK ) { + +/* Now indicate that the simplified uncertainty Region should be used. */ + ok = 1; + +/* Loop round all axes of the base Frame of "this". */ + for( ic = 0; ic < naxb; ic++ ) { + +/* Get the width of the two bounding boxes on this axis. */ + w1 = s1_ubnd[ ic ] - s1_lbnd[ ic ]; + w2 = s2_ubnd[ ic ] - s2_lbnd[ ic ]; + +/* If these differ by more than 0.1% then we determine that the simplified + uncertainty Region varies in size across the bounding box of "this", and + so we do not use the simplified uncertainty Region. The figure of 0.1% + is arbitrary. */ + if( fabs( w1 - w2 ) > 0.005*( fabs( w1 ) + fabs( w2 ) ) ) { + ok = 0; + break; + } + } + } + +/* Reinstate the original base Frame centre of the simplified uncertainty Region. */ + astRegCentre( sunc, orig_cen, NULL, 0, AST__BASE ); + +/* Free resources. */ + orig_cen = astFree( orig_cen ); + lbnd = astFree( lbnd ); + ubnd = astFree( ubnd ); + s1_lbnd = astFree( s1_lbnd ); + s1_ubnd = astFree( s1_ubnd ); + s2_lbnd = astFree( s2_lbnd ); + s2_ubnd = astFree( s2_ubnd ); + bfrm = astAnnul( bfrm ); + +/* If we can use the simplified uncertainty Region, indicate that we have + performed some simplification, and store the new uncertainty Region. */ + if( ok ) { + simpler = 1; + astSetUnc( new, sunc ); + } + } + +/* Free resources */ + unc = astAnnul( unc ); + sunc = astAnnul( sunc ); + } + +/* If any simplification could be performed, return the new Region. + Otherwise, return a clone of the supplied pointer. */ + if( simpler ){ + result = (AstMapping *) new; + } else { + new = astAnnul( new ); + result = astClone( this ); + } + +/* If an error occurred, annul the returned pointer. */ + if ( !astOK ) result = astAnnul( result ); + +/* Return the result. */ + return result; +} + +static int SubFrame( AstFrame *this_frame, AstFrame *template, + int result_naxes, + const int *target_axes, const int *template_axes, + AstMapping **map, AstFrame **result, int *status ) { +/* +* Name: +* SubFrame + +* Purpose: +* Select axes from a Region and convert to the new coordinate system. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int SubFrame( AstFrame *target, AstFrame *template, int result_naxes, +* const int *target_axes, const int *template_axes, +* AstMapping **map, AstFrame **result, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astSubFrame +* method inherited from the Frame class). + +* Description: +* This function selects a requested sub-set (or super-set) of the +* axes from the current Frame of a "target" Region and creates a +* new Frame with copies of the selected axes assembled in the +* requested order. It then optionally overlays the attributes of a +* "template" Frame on to the result. It returns both the resulting +* Frame and a Mapping that describes how to convert between the +* coordinate systems described by the current Frame of the target +* Region and the result Frame. If necessary, this Mapping takes +* account of any differences in the Frames' attributes due to the +* influence of the template. + +* Parameters: +* target +* Pointer to the target Region, from whose current Frame the +* axes are to be selected. +* template +* Pointer to the template Frame, from which new attributes for +* the result Frame are to be obtained. Optionally, this may be +* NULL, in which case no overlaying of template attributes will +* be performed. +* result_naxes +* Number of axes to be selected from the target Region. This +* number may be greater than or less than the number of axes in +* the Region's current Frame (or equal). +* target_axes +* Pointer to an array of int with result_naxes elements, giving +* a list of the (zero-based) axis indices of the axes to be +* selected from the current Frame of the target Region. The +* order in which these are given determines the order in which +* the axes appear in the result Frame. If any of the values in +* this array is set to -1, the corresponding result axis will +* not be derived from the target Region, but will be assigned +* default attributes instead. +* template_axes +* Pointer to an array of int with result_naxes elements. This +* should contain a list of the template axes (given as +* zero-based axis indices) with which the axes of the result +* Frame are to be associated. This array determines which axes +* are used when overlaying axis-dependent attributes of the +* template on to the result. If any element of this array is +* set to -1, the corresponding result axis will not receive any +* template attributes. +* +* If the template argument is given as NULL, this array is not +* used and a NULL pointer may also be supplied here. +* map +* Address of a location to receive a pointer to the returned +* Mapping. The forward transformation of this Mapping will +* describe how to convert coordinates from the coordinate +* system described by the current Frame of the target Region +* to that described by the result Frame. The inverse +* transformation will convert in the opposite direction. +* result +* Address of a location to receive a pointer to the result Frame. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* A non-zero value is returned if coordinate conversion is +* possible between the current Frame of the target Region and +* the result Frame. Otherwise zero is returned and *map and +* *result are returned as NULL (but this will not in itself result +* in an error condition). In general, coordinate conversion should +* always be possible if no template Frame is supplied but may not +* always be possible otherwise. + +* Notes: +* - A value of zero will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to Region's current Frame */ + int match; /* Result to be returned */ + +/* Initialise. */ + *map = NULL; + *result = NULL; + match = 0; + +/* Check the global error status. */ + if ( !astOK ) return match; + +/* Invoke the parent astSubFrame method on the Frame represented by the + region. */ + fr = astGetFrame( ((AstRegion *) this_frame)->frameset, AST__CURRENT ); + match = astSubFrame( fr, template, result_naxes, target_axes, template_axes, + map, result ); + fr = astAnnul( fr ); + +/* Return the result. */ + return match; +} + +static AstSystemType SystemCode( AstFrame *this_frame, const char *system, int *status ) { +/* +* Name: +* SystemCode + +* Purpose: +* Convert a string into a coordinate system type code. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astSystemCode +* method inherited from the Frame class). + +* Description: +* This function converts a string used for the external description of +* a coordinate system into a Frame coordinate system type code (System +* attribute value). It is the inverse of the astSystemString function. + +* Parameters: +* this +* Pointer to the Frame. +* system +* Pointer to a constant null-terminated string containing the +* external description of the coordinate system. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The System type code. + +* Notes: +* - A value of AST__BADSYSTEM is returned if the coordinate system +* description was not recognised. This does not produce an error. +* - A value of AST__BADSYSTEM is also returned if this function +* is invoked with the global error status set or if it should fail +* for any reason. +*/ + +/* Local Variables: */ + AstSystemType result; /* Result value to return */ + AstFrame *fr; /* Pointer to FrameSet's current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Initialise. */ + result = AST__BADSYSTEM; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke the + astSystemCode method for this Frame. Annul the Frame pointer afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astSystemCode( fr, system ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = AST__BADSYSTEM; + +/* Return the result. */ + return result; +} + +static const char *SystemString( AstFrame *this_frame, AstSystemType system, int *status ) { +/* +* Name: +* SystemString + +* Purpose: +* Convert a coordinate system type code into a string. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* const char *SystemString( AstFrame *this, AstSystemType system, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astSystemString +* method inherited from the Frame class). + +* Description: +* This function converts a Frame coordinate system type code +* (System attribute value) into a string suitable for use as an +* external representation of the coordinate system type. + +* Parameters: +* this +* Pointer to the Frame. +* system +* The coordinate system type code. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* Pointer to a constant null-terminated string containing the +* textual equivalent of the type code supplied. + +* Notes: +* - A NULL pointer value is returned if the coordinate system +* code was not recognised. This does not produce an error. +* - A NULL pointer value is also returned if this function is +* invoked with the global error status set or if it should fail +* for any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to FrameSet's current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + const char *result; /* Pointer value to return */ + +/* Initialise. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke the + astSystemString method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astSystemString( fr, system ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = NULL; + +/* Return the result pointer. */ + return result; + +} + +static int RegTrace( AstRegion *this, int n, double *dist, double **ptr, int *status ){ +/* +*+ +* Name: +* astRegTrace + +* Purpose: +* Return requested positions on the boundary of a 2D Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* int astRegTrace( AstRegion *this, int n, double *dist, double **ptr ); + +* Class Membership: +* Region virtual function + +* Description: +* This function returns positions on the boundary of the supplied +* Region, if possible. The required positions are indicated by a +* supplied list of scalar parameter values in the range zero to one. +* Zero corresponds to some arbitrary starting point on the boundary, +* and one corresponds to the end (which for a closed region will be +* the same place as the start). + +* Parameters: +* this +* Pointer to the Region. +* n +* The number of positions to return. If this is zero, the function +* returns without action (but the returned function value still +* indicates if the method is supported or not). +* dist +* Pointer to an array of "n" scalar parameter values in the range +* 0 to 1.0. +* ptr +* A pointer to an array of pointers. The number of elements in +* this array should equal tthe number of axes in the Frame spanned +* by the Region. Each element of the array should be a pointer to +* an array of "n" doubles, in which to return the "n" values for +* the corresponding axis. The contents of the arrays are unchanged +* if the supplied Region belongs to a class that does not +* implement this method. + +* Returned Value: +* Non-zero if the astRegTrace method is implemented by the class +* of Region supplied, and zero if not. + +*- +*/ + +/* Concrete sub-classes of Region must over-ride this method. */ + return 0; +} + +static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { +/* +* Name: +* TestAttrib + +* Purpose: +* Test if a specified attribute value is set for a Region. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int TestAttrib( AstObject *this, const char *attrib, int *status ) + +* Class Membership: +* Region member function (over-rides the astTestAttrib protected +* method inherited from the Frame class). + +* Description: +* This function returns a boolean result (0 or 1) to indicate whether +* a value has been set for one of a Region's attributes. + +* Parameters: +* this +* Pointer to the Region. +* attrib +* Pointer to a null terminated string specifying the attribute +* name. This should be in lower case with no surrounding white +* space. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* One if a value has been set, otherwise zero. + +* Notes: +* - A value of zero will be returned if this function is invoked +* with the global status set, or if it should fail for any reason. +*/ + +/* Local Variables: */ + AstRegion *this; /* Pointer to the Region structure */ + int result; /* Result value to return */ + +/* Initialise. */ + result = 0; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_object; + +/* Check the attribute name and test the appropriate attribute. */ + +/* We first handle attributes that apply to the Region as a whole + (rather than to the encapsulated FrameSet). */ + +/* Negated. */ +/* -------- */ + if ( !strcmp( attrib, "negated" ) ) { + result = astTestNegated( this ); + +/* Closed. */ +/* ------- */ + } else if ( !strcmp( attrib, "closed" ) ) { + result = astTestClosed( this ); + +/* FillFactor */ +/* ---------- */ + } else if ( !strcmp( attrib, "fillfactor" ) ) { + result = astTestFillFactor( this ); + +/* MeshSize */ +/* -------- */ + } else if ( !strcmp( attrib, "meshsize" ) ) { + result = astTestMeshSize( this ); + +/* Adaptive */ +/* -------- */ + } else if ( !strcmp( attrib, "adaptive" ) ) { + result = astTestAdaptive( this ); + +/* Now do attributes inherited from parent classes. This is so that the + attribute test will not be passed on to the encpasulated FrameSet below. */ + +/* ID. */ +/* --- */ + } else if ( !strcmp( attrib, "id" ) ) { + result = astTestID( this ); + +/* Ident. */ +/* ------ */ + } else if ( !strcmp( attrib, "ident" ) ) { + result = astTestIdent( this ); + +/* Invert. */ +/* ------- */ + } else if ( !strcmp( attrib, "invert" ) ) { + result = astTestInvert( this ); + +/* Report. */ +/* ------- */ + } else if ( !strcmp( attrib, "report" ) ) { + result = astTestReport( this ); + +/* If the name is not recognised, test if it matches any of the + read-only attributes of this class. If it does, then return + zero. */ + } else if ( !strcmp( attrib, "class" ) || + !strcmp( attrib, "nin" ) || + !strcmp( attrib, "nobject" ) || + !strcmp( attrib, "bounded" ) || + !strcmp( attrib, "nout" ) || + !strcmp( attrib, "refcount" ) || + !strcmp( attrib, "tranforward" ) || + !strcmp( attrib, "traninverse" ) ) { + result = 0; + +/* Pass unrecognised attributes on to the Region's encapsulated FrameSet for + further interpretation. Do not pass on FrameSet attributes since we + pretend to the outside world that the encapsulated FrameSet is actually a + Frame. */ + } else if ( strcmp( attrib, "base" ) && + strcmp( attrib, "current" ) && + strcmp( attrib, "nframe" ) ) { + result = astTestAttrib( this->frameset, attrib ); + } + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = 0; + +/* Return the result, */ + return result; +} + +double *astRegTranPoint_( AstRegion *this, double *in, int np, int forward, int *status ){ +/* +*+ +* Name: +* astRegTranPoint + +* Purpose: +* Transform points between the base and current Frames in a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* double *astRegTranPoint( AstRegion *this, double *in, int np, int forward ) + +* Class Membership: +* Region member function + +* Description: +* This function transforms one or more points between the base and +* current Frames of the FrameSet encapsulated by the supplied Region. + +* Parameters: +* this +* The Region pointer. +* in +* Pointer to a 1-d array holding the axis values to be transformed. +* If "forward" is non-zero, the number of axis values supplied for +* each position should equal the number of axes in the base Frame +* of the FrameSet encapsulated by "this". If "forward" is zero, the +* number of axis values supplied for each position should equal the +* number of axes in the current Frame of the FrameSet encapsulated by +* "this". All the axis values for a position should be in adjacent +* elements of the array. +* np +* The number of points supplied in "in". +* forward +* If non-zero, the supplied points are assumed to refer to the base +* Frame of the encapsulated FrameSet, and they are transformed to the +* current Frame. If zero, the supplied points are assumed to refer to +* the current Frame of the encapsulated FrameSet, and they are +* transformed to the base Frame. + +* Returned Value: +* Pointer to a new dynamically allocated array holding the +* transformed axis values. If "forward" is non-zero, the number of axis +* values for each position will be equal the number of axes in the +* current Frame of the FrameSet encapsulated by "this". If "forward" is +* zero, the number of axis values for each position will be equal to the +* number of axes in the base Frame of the FrameSet encapsulated by "this". +* All the axis values for a position will be in adjacent elements of the +* array. The array should be freed using astFree when no longer needed. + +* Notes: +* - A NULL pointer is returned if an error has already occurred, or if +* this function should fail for any reason. + +*- +*/ + +/* Local Variables: */ + AstMapping *map; + AstPointSet *pset_in; + AstPointSet *pset_out; + double **ptr_in; + double **ptr_out; + double *p; + double *result; + int ic; + int ip; + int naxin; + int naxout; + +/* Initialise */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Get a pointer to the required Mapping. */ + if( forward ) { + map = astGetMapping( this->frameset, AST__BASE, AST__CURRENT ); + } else { + map = astGetMapping( this->frameset, AST__CURRENT, AST__BASE ); + } + +/* Get the number of axis values per input and per output point. */ + naxin = astGetNin( map ); + naxout = astGetNout( map ); + +/* Create a pointSet holding the supplied axis values. */ + pset_in = astPointSet( np, naxin, "", status ); + +/* Get pointers to the memory used to store axis values within this + PointSet. */ + ptr_in = astGetPoints( pset_in ); + +/* Allocate the output array. */ + result = astMalloc( sizeof( double )*(size_t)( naxout*np ) ); + +/* Check the pointers can be used. */ + if( astOK ) { + +/* Store the supplied axis values in the PointSet memory. */ + p = in; + for( ip = 0; ip < np; ip++ ) { + for( ic = 0; ic < naxin; ic++ ) ptr_in[ ic ][ ip ] = *(p++); + } + +/* Transform the PointSet. */ + pset_out = astTransform( map, pset_in, 1, NULL ); + +/* Get a pointer to the memory in the transformed PointSet. */ + ptr_out = astGetPoints( pset_out ); + + if( pset_out && astStatus == AST__INTER ) { + p = in; + for( ip = 0; ip < np; ip++ ) { + for( ic = 0; ic < naxin; ic++ ) printf("%.*g\n", AST__DBL_DIG, *(p++) ); + } + } + + if( astOK ) { + +/* Store the resulting axis values in the output array. */ + p = result; + for( ip = 0; ip < np; ip++ ) { + for( ic = 0; ic < naxout; ic++ ) *(p++) = ptr_out[ ic ][ ip ]; + } + } + +/* Free resources. */ + pset_out = astAnnul( pset_out ); + } + pset_in = astAnnul( pset_in ); + map = astAnnul( map ); + +/* Return NULL if anything went wrong. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the result.*/ + return result; +} + +static AstPointSet *RegTransform( AstRegion *this, AstPointSet *in, + int forward, AstPointSet *out, AstFrame **frm, int *status ) { +/* +*+ +* Name: +* astRegTransform + +* Purpose: +* Transform a set of points using the encapsulated FrameSet. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstPointSet *astRegTransform( AstRegion *this, AstPointSet *in, +* int forward, AstPointSet *out, +* AstFrameSet **frm ) + +* Class Membership: +* Region virtual function + +* Description: +* This function takes a Region and a set of points encapsulated +* in a PointSet, and applies either the forward or inverse +* coordinate transformation represented by the encapsulated FrameSet. +* It also returned a pointer to either the current or base Frame in +* the FrameSet. + +* Parameters: +* this +* Pointer to the Region. +* in +* Pointer to the PointSet holding the input coordinate data. If +* NULL then the "points" PointSet within the supplied Region +* ("this") is used. +* forward +* A non-zero value indicates that the forward coordinate transformation +* (from base to current) should be applied, while a zero value requests +* the inverse transformation (from current to base). +* out +* Pointer to a PointSet which will hold the transformed (output) +* coordinate values. A NULL value may also be given, in which case a +* new PointSet will be created by this function. +* frm +* Location at which to return a pointer to a Frame. If "forward" +* is non-zero, the current Frame in the encapsulated FrameSet will +* be returned. Otherwise, the base Frame is returned. The returned +* pointer should be annulled when no longer needed. May be NULL if +* no pointer is needed. + +* Returned Value: +* Pointer to the output (possibly new) PointSet. If "out" is NULL, +* the returned pointer will be a clone of "in" if the Mapping is a +* UnitMap. If "out" is not NULL, then the supplied "out" PointSet will +* be used and returned. + +* Notes: +* - An error will result if the Region supplied does not define +* the requested coordinate transformation (either forward or +* inverse). +* - The number of coordinate values per point in the input +* PointSet must match the number of input coordinates for the +* Region being applied (or number of output coordinates if the +* inverse transformation is requested). This will be equal to the +* number of axes in the Region's base Frame (or the current +* Frame for the inverse transformation). +* - If an output PointSet is supplied, it must have space for +* sufficient number of points and coordinate values per point to +* accommodate the result (e.g. the number of Region output +* coordinates, or number of input coordinates if the inverse +* transformation is requested). Any excess space will be ignored. +* - A null pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Local Variables: */ + AstMapping *smap; /* Pointer to simplified Mapping */ + AstPointSet *result; /* Pointer value to return */ + +/* Initialise */ + if( frm ) *frm = NULL; + +/* Check the global error status. */ + if ( !astOK ) return NULL; + +/* If no input PointSet was provided, use the PointSet in the Region. */ + if( !in ) { + if( this->points ) { + in = this->points; + } else { + astError( AST__INTER, "astRegTransform(%s): No PointSet supplied " + "and the supplied %s has no PointSet (internal AST " + "programming error)", status, astGetClass( this ),astGetClass( this ) ); + } + } + +/* Get the simplified Mapping from base to current Frame. */ + smap = astRegMapping( this ); + +/* If it is a UnitMap, return a clone of the input PointSet unless an + explicit output PointSet has been supplied. */ + if( astIsAUnitMap( smap ) && !out ) { + result = astClone( in ); + +/* Otherwise use the Mapping to transform the supplied positions. */ + } else { + result = astTransform( smap, in, forward, out ); + } + +/* Return a pointer to the appropriate Frame. */ + if( frm ) *frm = astGetFrame( this->frameset, forward ? AST__CURRENT : AST__BASE ); + +/* Release resources. */ + smap = astAnnul( smap ); + +/* Return a pointer to the output PointSet. */ + return result; +} + +static int Unformat( AstFrame *this_frame, int axis, const char *string, + double *value, int *status ) { +/* +* Name: +* Unformat + +* Purpose: +* Read a formatted coordinate value for a Region axis. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int Unformat( AstFrame *this, int axis, const char *string, +* double *value, int *status ) + +* Class Membership: +* Region member function (over-rides the public astUnformat +* method inherited from the Frame class). + +* Description: +* This function reads a formatted coordinate value for a Region +* axis (supplied as a string) and returns the equivalent numerical +* value as a double. It also returns the number of characters read +* from the string. + +* Parameters: +* this +* Pointer to the Region. +* axis +* The number of the Region axis for which the coordinate +* value is to be read (axis numbering starts at zero for the +* first axis). +* string +* Pointer to a constant null-terminated string containing the +* formatted coordinate value. +* value +* Pointer to a double in which the coordinate value read will be +* returned. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The number of characters read from the string to obtain the +* coordinate value. + +* Notes: +* - Any white space at the beginning of the string will be +* skipped, as also will any trailing white space following the +* coordinate value read. The function's return value will reflect +* this. +* - A function value of zero (and no coordinate value) will be +* returned, without error, if the string supplied does not contain +* a suitably formatted value. +* - The string "<bad>" is recognised as a special case and will +* generate the value AST__BAD, without error. The test for this +* string is case-insensitive and permits embedded white space. +* - A function result of zero will be returned and no coordinate +* value will be returned via the "value" pointer if this function +* is invoked with the global error status set, or if it should +* fail for any reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + double coord; /* Coordinate value read */ + int nc; /* Number of characters read */ + +/* Initialise. */ + nc = 0; + +/* Check the global error status. */ + if ( !astOK ) return nc; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Validate the axis index. */ + (void) astValidateAxis( this, axis, 1, "astUnformat" ); + +/* Obtain a pointer to the Region's current Frame and invoke the + astUnformat method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + nc = astUnformat( fr, axis, string, &coord ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the number of characters read. */ + if ( !astOK ) { + nc = 0; + +/* Otherwise, if characters were read, return the coordinate value. */ + } else if ( nc ) { + *value = coord; + } + +/* Return the number of characters read. */ + return nc; +} + +static int ValidateAxis( AstFrame *this_frame, int axis, int fwd, + const char *method, int *status ) { +/* +* Name: +* ValidateAxis + +* Purpose: +* Validate and permute a Region's axis index. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int ValidateAxis( AstFrame *this, int axis, int fwd, const char *method, +* int *status ) + +* Class Membership: +* Region member function (over-rides the protected +* astValidateAxis method inherited from the Frame class). + +* Description: +* This function checks the validity of an index (zero-based) which +* is to be used to address one of the coordinate axes of the +* current Frame in a Region. If the index is valid, it is +* permuted using the axis permutation array associated with the +* Region's current Frame and the (zero-based) permuted axis +* index is returned. This gives the index the axis had when the +* Frame was first created. If the axis index supplied is not +* valid, an error is reported and the global error status is set. + +* Parameters: +* this +* Pointer to the Region. +* axis +* The axis index (zero-based) to be checked. To be valid, it +* must lie between zero and (naxes-1) inclusive, where "naxes" +* is the number of coordinate axes associated with the +* Region's current Frame. +* fwd +* If non-zero, the suppplied axis index is assumed to be an +* "external" axis index, and the corresponding "internal" axis index +* is returned as the function value. Otherwise, the suppplied axis +* index is assumed to be an "internal" axis index, and the +* corresponding "external" axis index is returned as the function +* value. +* method +* Pointer to a constant null-terminated character string +* containing the name of the method that invoked this function +* to validate an axis index. This method name is used solely +* for constructing error messages. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The permuted axis index - either "internal" or "external" as +* specified by "fwd". + +* Notes: +* - A value of zero will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + int naxes; /* Number of Region axes */ + int result; /* Permuted axis index */ + +/* Initialise. */ + result = 0; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_frame; + +/* Determine the number of Region axes. */ + naxes = astGetNaxes( this ); + if ( astOK ) { + +/* If the Region has no axes, report an error (convert to 1-based + axis numbering for the benefit of the public interface). */ + if ( naxes == 0 ) { + astError( AST__AXIIN, "%s(%s): Invalid attempt to use an axis index " + "(%d) for a %s which has no axes.", status, method, + astGetClass( this ), axis + 1, astGetClass( this ) ); + +/* Otherwise, check the axis index for validity and report an error if + it is not valid (again, convert to 1-based axis numbering). */ + } else if ( ( axis < 0 ) || ( axis >= naxes ) ) { + astError( AST__AXIIN, "%s(%s): Axis index (%d) invalid - it should " + "be in the range 1 to %d.", status, method, astGetClass( this ), + axis + 1, naxes ); + +/* If the axis index was valid, obtain a pointer to the Region's + current Frame and invoke this Frame's astValidateAxis method to + obtain the permuted axis index. Annul the Frame pointer + afterwards. */ + } else { + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astValidateAxis( fr, axis, fwd, "astValidateAxis" ); + fr = astAnnul( fr ); + } + } + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = 0; + +/* Return the result. */ + return result; +} + +static void ValidateAxisSelection( AstFrame *this_frame, int naxes, + const int *axes, const char *method, int *status ) { +/* +* Name: +* ValidateAxisSelection + +* Purpose: +* Check that a set of axes selected from a Frame is valid. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* void ValidateAxisSelection( AstFrame *this, int naxes, +* const int *axes, const char *method, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astValidateAxisSelection +* method inherited from the Frame class). + +* Description: +* This function checks the validity of an array of (zero-based) +* axis indices that specify a set of axes to be selected from a +* Frame. To be valid, no axis should be selected more than +* once. In assessing this, any axis indices that do not refer to +* valid Frame axes (e.g. are set to -1) are ignored. +* +* If the axis selection is valid, this function returns without further +* action. Otherwise, an error is reported and the global error status is +* set. + +* Parameters: +* this +* Pointer to the Frame. +* naxes +* The number of axes to be selected (may be zero). +* axes +* Pointer to an array of int with naxes elements that contains the +* (zero based) axis indices to be checked. +* method +* Pointer to a constant null-terminated character string +* containing the name of the method that invoked this function +* to validate an axis selection. This method name is used +* solely for constructing error messages. +* status +* Pointer to the inherited status variable. +*/ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke this + Frame's astValidateAxisSelection method. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + astValidateAxisSelection( fr, naxes, axes, method ); + fr = astAnnul( fr ); + +} + +static int ValidateSystem( AstFrame *this_frame, AstSystemType system, const char *method, int *status ) { +/* +* Name: +* ValidateSystem + +* Purpose: +* Validate a value for a Frame's System attribute. + +* Type: +* Private function. + +* Synopsis: +* #include "region.h" +* int ValidateSystem( AstFrame *this, AstSystemType system, +* const char *method, int *status ) + +* Class Membership: +* Region member function (over-rides the protected astValidateSystem +* method inherited from the Frame class). + +* Description: +* This function checks the validity of the supplied system value. +* If the value is valid, it is returned unchanged. Otherwise, an +* error is reported and a value of AST__BADSYSTEM is returned. + +* Parameters: +* this +* Pointer to the Frame. +* system +* The system value to be checked. +* method +* Pointer to a constant null-terminated character string +* containing the name of the method that invoked this function +* to validate an axis index. This method name is used solely +* for constructing error messages. +* status +* Pointer to the inherited status variable. + +* Returned Value: +* The validated system value. + +* Notes: +* - A value of AST_BADSYSTEM will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Local Variables: */ + AstSystemType result; /* Validated system value */ + AstFrame *fr; /* Pointer to FrameSet's current Frame */ + AstRegion *this; /* Pointer to the Region structure */ + +/* Initialise. */ + result = AST__BADSYSTEM; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Obtain a pointer to the FrameSet structure. */ + this = (AstRegion *) this_frame; + +/* Obtain a pointer to the Region's encapsulated Frame and invoke the + astValidateSystem method for this Frame. Annul the Frame pointer + afterwards. */ + fr = astGetFrame( this->frameset, AST__CURRENT ); + result = astValidateSystem( this, system, method ); + fr = astAnnul( fr ); + +/* If an error occurred, clear the result value. */ + if ( !astOK ) result = AST__BADSYSTEM; + +/* Return the result. */ + return result; +} + +/* Region Attributes. */ +/* -------------------- */ + +/* +*att++ +* Name: +* Adaptive + +* Purpose: +* Should the area adapt to changes in the coordinate system? + +* Type: +* Public attribute. + +* Synopsis: +* Integer (boolean). + +* Description: +* The coordinate system represented by a Region may be changed by +* assigning new values to attributes such as System, Unit, etc. +* For instance, a Region representing an area on the sky in ICRS +* coordinates may have its System attribute changed so that it +* represents (say) Galactic coordinates instead of ICRS. This +* attribute controls what happens when the coordinate system +* represented by a Region is changed in this way. +* +* If Adaptive is non-zero (the default), then area represented by the +* Region adapts to the new coordinate system. That is, the numerical +* values which define the area represented by the Region are changed +* by mapping them from the old coordinate system into the new coordinate +* system. Thus the Region continues to represent the same physical +* area. +* +* If Adaptive is zero, then area represented by the Region does not adapt +* to the new coordinate system. That is, the numerical values which +* define the area represented by the Region are left unchanged. Thus +* the physical area represented by the Region will usually change. +* +* As an example, consider a Region describe a range of wavelength from +* 2000 Angstrom to 4000 Angstrom. If the Unit attribute for the Region +* is changed from Angstrom to "nm" (nanometre), what happens depends +* on the setting of Adaptive. If Adaptive is non-zero, the Mapping +* from the old to the new coordinate system is found. In this case it +* is a simple scaling by a factor of 0.1 (since 1 Angstrom is 0.1 nm). +* This Mapping is then used to modify the numerical values within the +* Region, changing 2000 to 200 and 4000 to 400. Thus the modified +* region represents 200 nm to 400 nm, the same physical space as +* the original 2000 Angstrom to 4000 Angstrom. However, if Adaptive +* had been zero, then the numerical values would not have been changed, +* resulting in the final Region representing 2000 nm to 4000 nm. +* +* Setting Adaptive to zero can be necessary if you want correct +* inaccurate attribute settings in an existing Region. For instance, +* when creating a Region you may not know what Epoch value to use, so +* you would leave Epoch unset resulting in some default value being used. +* If at some later point in the application, the correct Epoch value +* is determined, you could assign the correct value to the Epoch +* attribute. However, you would first need to set Adaptive temporarily +* to zero, because otherwise the area represented by the Region would +* be Mapped from the spurious default Epoch to the new correct Epoch, +* which is not what is required. + +* Applicability: +* Region +* All Regions have this attribute. +*att-- +*/ + +/* This is a boolean value (0 or 1) with a value of -INT_MAX when + undefined but yielding a default of 1. */ +astMAKE_CLEAR(Region,Adaptive,adaptive,-INT_MAX) +astMAKE_GET(Region,Adaptive,int,1,( ( this->adaptive == -INT_MAX ) ? + 1 : this->adaptive )) +astMAKE_SET(Region,Adaptive,int,adaptive,( value != 0 )) +astMAKE_TEST(Region,Adaptive,( this->adaptive != -INT_MAX )) + +/* +*att++ +* Name: +* Negated + +* Purpose: +* Region negation flag. + +* Type: +* Public attribute. + +* Synopsis: +* Integer (boolean). + +* Description: +* This attribute controls whether a Region represents the "inside" or +* the "outside" of the area which was supplied when the Region was +* created. If the attribute value is zero (the default), the Region +* represents the inside of the original area. However, if it is non-zero, +* it represents the outside of the original area. The value of this +* attribute may be toggled using the +c astNegate function. +f AST_NEGATE routine. + +* Note, whether the boundary is considered to be inside the Region or +* not is controlled by the Closed attribute. Changing the value of +* the Negated attribute does not change the value of the Closed attribute. +* Thus, if Region is closed, then the boundary of the Region will be +* inside the Region, whatever the setting of the Negated attribute. + +* Applicability: +* Region +* All Regions have this attribute. +*att-- +*/ + +/* This is a boolean value (0 or 1) with a value of -INT_MAX when + undefined but yielding a default of zero. */ +astMAKE_CLEAR(Region,Negated,negated,(astResetCache(this),-INT_MAX)) +astMAKE_GET(Region,Negated,int,0,( ( this->negated == -INT_MAX ) ? + 0 : this->negated )) +astMAKE_SET(Region,Negated,int,negated,(astResetCache(this),( value != 0 ))) +astMAKE_TEST(Region,Negated,( this->negated != -INT_MAX )) + +/* +*att++ +* Name: +* Bounded + +* Purpose: +* Is the Region bounded? + +* Type: +* Public attribute. + +* Synopsis: +* Integer (boolean), read-only. + +* Description: +* This is a read-only attribute indicating if the Region is bounded. +* A Region is bounded if it is contained entirely within some +* finite-size bounding box. + +* Applicability: +* Region +* All Regions have this attribute. +*att-- +*/ + +/* +*att+ +* Name: +* RegionFS + +* Purpose: +* Should Region FrameSet be dumped? + +* Type: +* Protected attribute. + +* Synopsis: +* Integer (boolean). + +* Description: +* This attribute indicates whether the FrameSet encapsulated by the +* Region should be included in the dump produced by the Dump function. +* +* If set to a non-zero value (the default), the FrameSet in the Region +* will always be included in the dump as usual. If set to zero, the +* FrameSet will only be included in the dump if the Mapping from base +* to current Frame is not a UnitMap. If the base->current Mapping is +* a UnitMap, the FrameSet is omitted from the dump. If the dump is +* subsequently used to re-create the Region, the new Region will have a +* default FrameSet containing a single default Frame with the appropriate +* number of axes. +* +* This facility is indended to reduce the size of textual dumps of +* Regions in situations where the Frame to which the Region refers can +* be implied by the context in which the Region is used. This is +* often the case when a Region is encapsulated within another Region. +* In such cases the current Frame of the encapsulated Region will +* usually be equivalent to the base Frame of the parent Region +* structure, and so can be re-instated (by calling the astSetRegFS +* method) even if the FrameSet is omitted from the dump of the +* encapsulated Region. Note if the base->current Mapping in the FrameSet +* in the encapsulated Region is not a UnitMap, then we should always +* dump the FrameSet regardless of the setting of RegionFS. This is because +* the parent Region structure will not know how to convert the PointSet +* stored in the encapsulated Region into its own base Frame if the +* FrameSet is not available. + +* Applicability: +* Region +* All Regions have this attribute. +*att- +*/ + +/* This is a boolean value (0 or 1) with a value of -INT_MAX when + undefined but yielding a default of one. */ +astMAKE_CLEAR(Region,RegionFS,regionfs,-INT_MAX) +astMAKE_TEST(Region,RegionFS,( this->regionfs != -INT_MAX )) +astMAKE_SET(Region,RegionFS,int,regionfs,( value != 0 )) +astMAKE_GET(Region,RegionFS,int,1,( ( this->regionfs == -INT_MAX ) ? + 1 : this->regionfs )) + +/* +*att++ +* Name: +* FillFactor + +* Purpose: +* Fraction of the Region which is of interest. + +* Type: +* Public attribute. + +* Synopsis: +* Floating point. + +* Description: +* This attribute indicates the fraction of the Region which is of +* interest. AST does not use this attribute internally for any purpose. +* Typically, it could be used to indicate the fraction of the Region for +* which data is available. +* +* The supplied value must be in the range 0.0 to 1.0, and the default +* value is 1.0 (except as noted below). + +* Applicability: +* Region +* All Regions have this attribute. +* CmpRegion +* The default FillFactor for a CmpRegion is the FillFactor of its +* first component Region. +* Prism +* The default FillFactor for a Prism is the product of the +* FillFactors of its two component Regions. +* Stc +* The default FillFactor for an Stc is the FillFactor of its +* encapsulated Region. +*att-- +*/ + +astMAKE_CLEAR(Region,FillFactor,fillfactor,AST__BAD) +astMAKE_GET(Region,FillFactor,double,1.0,( ( this->fillfactor == AST__BAD ) ? + 1.0 : this->fillfactor )) +astMAKE_TEST(Region,FillFactor,( this->fillfactor != AST__BAD )) +astMAKE_SET(Region,FillFactor,double,fillfactor,((value<0.0||value>1.0)?( + astError(AST__ATSER,"astSetFillFactor(%s): Invalid value (%g) supplied " + "for attribute FillFactor.", status,astGetClass(this),value), + astError(AST__ATSER,"FillFactor values should be in the range 0.0 to 1.0", status), + this->fillfactor):value)) + +/* +*att++ +* Name: +* MeshSize + +* Purpose: +* Number of points used to represent the boundary of a Region. + +* Type: +* Public attribute. + +* Synopsis: +* Integer. + +* Description: +* This attribute controls how many points are used when creating a +* mesh of points covering the boundary or volume of a Region. Such a +* mesh is returned by the +c astGetRegionMesh +f AST_GETREGIONMESH +* method. The boundary mesh is also used when testing for overlap +* between two Regions: each point in the bomdary mesh of the first +* Region is checked to see if it is inside or outside the second Region. +* Thus, the reliability of the overlap check depends on the value assigned +* to this attribute. If the value used is very low, it is possible for +* overlaps to go unnoticed. High values produce more reliable results, but +* can result in the overlap test being very slow. The default value is 200 +* for two dimensional Regions and 2000 for three or more dimensional +* Regions (this attribute is not used for 1-dimensional regions since the +* boundary of a simple 1-d Region can only ever have two points). A +* value of five is used if the supplied value is less than five. + +* Applicability: +* Region +* All Regions have this attribute. +* CmpRegion +* The default MeshSize for a CmpRegion is the MeshSize of its +* first component Region. +* Stc +* The default MeshSize for an Stc is the MeshSize of its +* encapsulated Region. +*att-- +*/ +/* If the value of MeshSize is set or cleared, annul the PointSet used to + cache a mesh of base Frame boundary points. This will force a new + PointSet to be created next time it is needed. See function RegMesh. */ +astMAKE_CLEAR(Region,MeshSize,meshsize,(astResetCache(this),-INT_MAX)) +astMAKE_SET(Region,MeshSize,int,meshsize,(astResetCache(this),( value > 5 ? value : 5 ))) +astMAKE_TEST(Region,MeshSize,( this->meshsize != -INT_MAX )) +astMAKE_GET(Region,MeshSize,int,0,( ( this->meshsize == -INT_MAX)?((astGetNaxes(this)==1)?2:((astGetNaxes(this)==2)?200:2000)): this->meshsize )) + +/* +*att++ +* Name: +* Closed + +* Purpose: +* Should the boundary be considered to be inside the region? + +* Type: +* Public attribute. + +* Synopsis: +* Integer (boolean). + +* Description: +* This attribute controls whether points on the boundary of a Region +* are considered to be inside or outside the region. If the attribute +* value is non-zero (the default), points on the boundary are considered +* to be inside the region (that is, the Region is "closed"). However, +* if the attribute value is zero, points on the bounary are considered +* to be outside the region. + +* Applicability: +* Region +* All Regions have this attribute. +* PointList +* The value of the Closed attribute is ignored by PointList regions. +* If the PointList region has not been negated, then it is always +* assumed to be closed. If the PointList region has been negated, then +* it is always assumed to be open. This is required since points +* have zero volume and therefore consist entirely of boundary. +* CmpRegion +* The default Closed value for a CmpRegion is the Closed value of its +* first component Region. +* Stc +* The default Closed value for an Stc is the Closed value of its +* encapsulated Region. +*att-- +*/ +/* This is a boolean value (0 or 1) with a value of -INT_MAX when + undefined but yielding a default of 1. */ +astMAKE_CLEAR(Region,Closed,closed,(astResetCache(this),-INT_MAX)) +astMAKE_GET(Region,Closed,int,1,( ( this->closed == -INT_MAX ) ? + 1 : this->closed )) +astMAKE_SET(Region,Closed,int,closed,(astResetCache(this),( value != 0 ))) +astMAKE_TEST(Region,Closed,( this->closed != -INT_MAX )) + +/* Access to attributes of the encapsulated Frame. */ +/* ----------------------------------------------- */ +/* Use the macros defined at the start of this file to implement + private member functions that give access to the attributes of the + encapsulated Frame of a Region and its axes. These functions over-ride + the attribute access methods inherited from the Frame class. */ + +/* Clear, Get, Set and Test axis-independent Frame attributes. */ +MAKE_CLEAR(Digits) +MAKE_CLEAR(Domain) +MAKE_CLEAR(MatchEnd) +MAKE_CLEAR(MaxAxes) +MAKE_CLEAR(MinAxes) +MAKE_CLEAR(Permute) +MAKE_CLEAR(PreserveAxes) +MAKE_CLEAR(Title) + +MAKE_GET(Digits,int) +MAKE_GET(Domain,const char *) +MAKE_GET(MatchEnd,int) +MAKE_GET(MaxAxes,int) +MAKE_GET(MinAxes,int) +MAKE_GET(Permute,int) +MAKE_GET(PreserveAxes,int) +MAKE_GET(Title,const char *) +MAKE_SET(Digits,int,I) +MAKE_SET(Domain,const char *,C) +MAKE_SET(MatchEnd,int,I) +MAKE_SET(MaxAxes,int,I) +MAKE_SET(MinAxes,int,I) +MAKE_SET(Permute,int,I) +MAKE_SET(PreserveAxes,int,I) +MAKE_SET(Title,const char *,C) +MAKE_TEST(Digits) +MAKE_TEST(Domain) +MAKE_TEST(MatchEnd) +MAKE_TEST(MaxAxes) +MAKE_TEST(MinAxes) +MAKE_TEST(Permute) +MAKE_TEST(PreserveAxes) +MAKE_TEST(Title) + +MAKE_GET(ActiveUnit,int) +MAKE_SET(ActiveUnit,int,I) +MAKE_TEST(ActiveUnit) + +MAKE_GET(System,AstSystemType) +MAKE_SET_SYSTEM(System) +MAKE_TEST(System) +MAKE_CLEAR(System) + +MAKE_GET(AlignSystem,AstSystemType) +MAKE_SET_SYSTEM(AlignSystem) +MAKE_TEST(AlignSystem) +MAKE_CLEAR(AlignSystem) + +MAKE_GET(Epoch,double) +MAKE_SET(Epoch,double,D) +MAKE_TEST(Epoch) +MAKE_CLEAR(Epoch) + +MAKE_GET(ObsLon,double) +MAKE_SET(ObsLon,double,D) +MAKE_TEST(ObsLon) +MAKE_CLEAR(ObsLon) + +MAKE_GET(ObsLat,double) +MAKE_SET(ObsLat,double,D) +MAKE_TEST(ObsLat) +MAKE_CLEAR(ObsLat) + +MAKE_GET(ObsAlt,double) +MAKE_SET(ObsAlt,double,D) +MAKE_TEST(ObsAlt) +MAKE_CLEAR(ObsAlt) + +/* Clear, Get, Set and Test axis-dependent Frame attributes. */ +MAKE_CLEAR_AXIS(Direction) +MAKE_CLEAR_AXIS(Format) +MAKE_CLEAR_AXIS(Label) +MAKE_CLEAR_AXIS(Symbol) +MAKE_CLEAR_AXIS(Unit) +MAKE_GET_AXIS(Direction,int) +MAKE_GET_AXIS(Format,const char *) +MAKE_GET_AXIS(Label,const char *) +MAKE_GET_AXIS(Symbol,const char *) +MAKE_GET_AXIS(Unit,const char *) +MAKE_SET_AXIS(Direction,int,I) +MAKE_SET_AXIS(Format,const char *,C) +MAKE_SET_AXIS(Label,const char *,C) +MAKE_SET_AXIS(Symbol,const char *,C) +MAKE_SET_AXIS(Unit,const char *,C) +MAKE_TEST_AXIS(Direction) +MAKE_TEST_AXIS(Format) +MAKE_TEST_AXIS(Label) +MAKE_TEST_AXIS(Symbol) +MAKE_TEST_AXIS(Unit) + +MAKE_GET_AXIS(Bottom,double) +MAKE_SET_AXIS(Bottom,double,D) +MAKE_TEST_AXIS(Bottom) +MAKE_CLEAR_AXIS(Bottom) + +MAKE_GET_AXIS(Top,double) +MAKE_SET_AXIS(Top,double,D) +MAKE_TEST_AXIS(Top) +MAKE_CLEAR_AXIS(Top) + +/* Copy constructor. */ +/* ----------------- */ +static void Copy( const AstObject *objin, AstObject *objout, int *status ) { +/* +* Name: +* Copy + +* Purpose: +* Copy constructor for Region objects. + +* Type: +* Private function. + +* Synopsis: +* void Copy( const AstObject *objin, AstObject *objout, int *status ) + +* Description: +* This function implements the copy constructor for Region objects. + +* Parameters: +* objin +* Pointer to the object to be copied. +* objout +* Pointer to the object being constructed. +* status +* Pointer to the inherited status variable. + +* Notes: +* - This constructor makes a deep copy. +*/ + +/* Local Variables: */ + AstRegion *in; /* Pointer to input Region */ + AstRegion *out; /* Pointer to output Region */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain pointers to the input and output Regions. */ + in = (AstRegion *) objin; + out = (AstRegion *) objout; + +/* For safety, first clear any references to the input memory from + the output Region. */ + out->basemesh = NULL; + out->basegrid = NULL; + out->frameset = NULL; + out->points = NULL; + out->unc = NULL; + out->negation = NULL; + out->defunc = NULL; + +/* Now copy each of the above structures. */ + out->frameset = astCopy( in->frameset ); + if( in->points ) out->points = astCopy( in->points ); + if( in->basemesh ) out->basemesh = astCopy( in->basemesh ); + if( in->basegrid ) out->basegrid = astCopy( in->basegrid ); + if( in->unc ) out->unc = astCopy( in->unc ); + if( in->negation ) out->negation = astCopy( in->negation ); + if( in->defunc ) out->defunc = astCopy( in->defunc ); +} + + +/* Destructor. */ +/* ----------- */ +static void Delete( AstObject *obj, int *status ) { +/* +* Name: +* Delete + +* Purpose: +* Destructor for Region objects. + +* Type: +* Private function. + +* Synopsis: +* void Delete( AstObject *obj, int *status ) + +* Description: +* This function implements the destructor for Region objects. + +* Parameters: +* obj +* Pointer to the object to be deleted. +* status +* Pointer to the inherited status variable. + +* Notes: +* This function attempts to execute even if the global error status is +* set. +*/ + +/* Local Variables: */ + AstRegion *this; /* Pointer to Region */ + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) obj; + +/* Annul all resources. */ + this->frameset = astAnnul( this->frameset ); + if( this->points ) this->points = astAnnul( this->points ); + if( this->basemesh ) this->basemesh = astAnnul( this->basemesh ); + if( this->basegrid ) this->basegrid = astAnnul( this->basegrid ); + if( this->unc ) this->unc = astAnnul( this->unc ); + if( this->negation ) this->negation = astAnnul( this->negation ); + if( this->defunc ) this->defunc = astAnnul( this->defunc ); +} + +/* Dump function. */ +/* -------------- */ +static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { +/* +* Name: +* Dump + +* Purpose: +* Dump function for Region objects. + +* Type: +* Private function. + +* Synopsis: +* void Dump( AstObject *this, AstChannel *channel, int *status ) + +* Description: +* This function implements the Dump function which writes out data +* for the Region class to an output Channel. + +* Parameters: +* this +* Pointer to the Region whose data are being written. +* channel +* Pointer to the Channel to which the data are being written. +* status +* Pointer to the inherited status variable. +*/ + +/* Local Constants: */ +#define KEY_LEN 50 /* Maximum length of a keyword */ +#define COM_LEN 50 /* Maximum length of a comment */ + +/* Local Variables: */ + AstFrame *fr; /* Pointer to the current Frame */ + AstMapping *smap; /* Base->current Mapping */ + AstRegion *this; /* Pointer to the Region structure */ + AstRegion *unc; /* Pointer to the uncertainty Region */ + double dval; /* Floating point attribute value */ + int ival; /* Integer attribute value */ + int set; /* Attribute value set? */ + int unit; /* Base->current is unitmap? */ + +/* Check the global error status. */ + if ( !astOK ) return; + +/* Obtain a pointer to the Region structure. */ + this = (AstRegion *) this_object; + +/* Write out values representing the instance variables for the + Region class. Accompany these with appropriate comment strings, + possibly depending on the values being written.*/ + +/* In the case of attributes, we first use the appropriate (private) + Test... member function to see if they are set. If so, we then use + the (private) Get... function to obtain the value to be written + out. + + For attributes which are not set, we use the astGet... method to + obtain the value instead. This will supply a default value + (possibly provided by a derived class which over-rides this method) + which is more useful to a human reader as it corresponds to the + actual default attribute value. Since "set" will be zero, these + values are for information only and will not be read back. */ + +/* Negated. */ +/* -------- */ + set = TestNegated( this, status ); + ival = set ? GetNegated( this, status ) : astGetNegated( this ); + astWriteInt( channel, "Negate", (ival != 0), 0, ival, + ival ? "Region negated" : "Region not negated" ); + +/* FillFactor */ +/* ---------- */ + set = TestFillFactor( this, status ); + dval = set ? GetFillFactor( this, status ) : astGetFillFactor( this ); + astWriteDouble( channel, "Fill", set, 0, dval,"Region fill factor" ); + +/* MeshSize. */ +/* --------- */ + set = TestMeshSize( this, status ); + ival = set ? GetMeshSize( this, status ) : astGetMeshSize( this ); + astWriteInt( channel, "MeshSz", set, 0, ival, + "No. of points used to represent boundary" ); + +/* Closed. */ +/* ------- */ + set = TestClosed( this, status ); + ival = set ? GetClosed( this, status ) : astGetClosed( this ); + astWriteInt( channel, "Closed", set, 0, ival, + ival ? "Boundary is inside" : "Boundary is outside" ); + +/* Adaptive */ +/* -------- */ + set = TestAdaptive( this, status ); + ival = set ? GetAdaptive( this, status ) : astGetAdaptive( this ); + astWriteInt( channel, "Adapt", (ival != 0), 0, ival, + ival ? "Region adapts to coord sys changes" : "Region does not adapt to coord sys changes" ); + +/* FrameSet */ +/* -------- */ + +/* If the vertices are the same in both base and current Frames (i.e. + if the Frames are connected by a UnitMap), then just dump the current + Frame (unless the RegionFS attribute is zero, in which case the + current Frame can be determined from the higher level context of the + Region and so does not need to be dumped- e.g. if the Region is contained + within another Region the parent Region will define the current Frame). + Otherwise, dump the whole FrameSet. */ + ival = astGetRegionFS( this ); + smap = astRegMapping( this ); + if( ( unit = astIsAUnitMap( smap ) ) ){ + set = 0; + if( ival ) { + fr = astGetFrame( this->frameset, AST__CURRENT ); + astWriteObject( channel, "Frm", 1, 1, fr, "Coordinate system" ); + fr = astAnnul( fr ); + } + } else { + set = ( ival == 0 ); + astWriteObject( channel, "FrmSet", 1, 1, this->frameset, + "Original & current coordinate systems" ); + } + +/* Annul the Mapping pointers */ + smap = astAnnul( smap ); + +/* RegionFS */ +/* -------- */ + astWriteInt( channel, "RegFS", set, 0, ival, + ival ? "Include Frame in dump" : "Do not include Frame in dump" ); + +/* Points */ +/* ------ */ + if( this->points ) { + astWriteObject( channel, "Points", 1, 1, this->points, + "Points defining the shape" ); + +/* If the FrameSet was not included in the dump, then the loader will use + the PointSet to determine the number of axes in the frame spanned by + the Region. If there is no PointSet, then we must explicitly include + an item giving the number of axes.*/ + } else { + astWriteInt( channel, "RegAxes", 1, 1, astGetNaxes( this ), + "Number of axes spanned by the Region" ); + } + +/* Uncertainty */ +/* ----------- */ +/* Only dump the uncertinaty Region if required. */ + if( astTestUnc( this ) ) { + unc = astGetUncFrm( this, AST__BASE ); + astWriteObject( channel, "Unc", 1, 1, unc, + "Region defining positional uncertainties." ); + unc = astAnnul( unc ); + } + +/* Undefine macros local to this function. */ +#undef KEY_LEN +} + + +/* Standard class functions. */ +/* ========================= */ +/* Implement the astIsARegion and astCheckRegion functions using + the macros defined for this purpose in the "object.h" header + file. */ +astMAKE_ISA(Region,Frame) +astMAKE_CHECK(Region) + +AstRegion *astInitRegion_( void *mem, size_t size, int init, + AstRegionVtab *vtab, const char *name, + AstFrame *frame, AstPointSet *pset, + AstRegion *unc, int *status ){ +/* +*+ +* Name: +* astInitRegion + +* Purpose: +* Initialise a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstRegion *astInitRegion( void *mem, size_t size, int init, +* AstRegionVtab *vtab, const char *name, +* AstFrame *frame, AstpointSet *pset, +* AstRegion *unc ) + +* Class Membership: +* Region initialiser. + +* Description: +* This function is provided for use by class implementations to +* initialise a new Region object. It allocates memory (if +* necessary) to accommodate the Region plus any additional data +* associated with the derived class. It then initialises a +* Region structure at the start of this memory. If the "init" +* flag is set, it also initialises the contents of a virtual +* function table for a Region at the start of the memory passed +* via the "vtab" parameter. + +* Parameters: +* mem +* A pointer to the memory in which the Region is to be +* created. This must be of sufficient size to accommodate the +* Region data (sizeof(Region)) plus any data used by the +* derived class. If a value of NULL is given, this function +* will allocate the memory itself using the "size" parameter to +* determine its size. +* size +* The amount of memory used by the Region (plus derived class +* data). This will be used to allocate memory if a value of +* NULL is given for the "mem" parameter. This value is also +* stored in the Region structure, so a valid value must be +* supplied even if not required for allocating memory. +* init +* A logical flag indicating if the Region's virtual function +* table is to be initialised. If this value is non-zero, the +* virtual function table will be initialised by this function. +* vtab +* Pointer to the start of the virtual function table to be +* associated with the new Region. +* name +* Pointer to a constant null-terminated character string which +* contains the name of the class to which the new object +* belongs (it is this pointer value that will subsequently be +* returned by the astGetClass method). +* frame +* Pointer to the encapsulated Frame. A deep copy of this Frame is +* taken. This means that subsequent changes to the supplied Frame +* will have no effect on the new Region. +* pset +* A PointSet holding the points which define the Region. These +* positions should refer to the given Frame. May be NULL. +* unc +* A pointer to a Region which specifies the uncertainty in the +* supplied positions (all points on the boundary of the new Region +* being initialised are assumed to have the same uncertainty). A NULL +* pointer can be supplied, in which case default uncertainties equal to +* 1.0E-6 of the dimensions of the new Region's bounding box are used. +* If an uncertainty Region is supplied, it must be of a class for +* which all instances are centro-symetric (e.g. Box, Circle, Ellipse, +* etc.) or be a Prism containing centro-symetric component Regions. +* Its encapsulated Frame must be related to the Frame supplied for +* parameter "frame" (i.e. astConvert should be able to find a Mapping +* between them). Two positions in the "frame" Frame are considered to be +* co-incident if their uncertainty Regions overlap. The centre of the +* supplied uncertainty Region is immaterial since it will be re-centred +* on the point being tested before use. A deep copy is taken of the +* supplied Region. + +* Returned Value: +* A pointer to the new Region. + +* Notes: +* - A null pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Local Variables: */ + AstFrame *f0; /* Frame to use */ + AstRegion *new; /* Pointer to new Region */ + int nax; /* No. of axes in supplied Frame */ + int ncoord; /* Coords per point */ + +/* Check the global status. */ + if ( !astOK ) return NULL; + +/* If necessary, initialise the virtual function table. */ + if( init ) astInitRegionVtab( vtab, name ); + +/* Note the number of axes in the supplied Frame. */ + nax = astGetNaxes( frame ); + +/* Check the pointset if supplied. */ + if( pset ) { + +/* Note the number of axes per point in the supplied PointSet */ + ncoord = astGetNcoord( pset ); + +/* If OK, check that the number of coordinates per point matches the number + of axes in the Frame. Report an error if these numbers do not match. */ + if ( astOK && ( ncoord != nax ) ) { + astError( AST__NCPIN, "astInitRegion(%s): Bad number of coordinate " + "values per point (%d).", status, name, ncoord ); + astError( AST__NCPIN, "The %s given requires %d coordinate value(s) " + "for each point.", status, astGetClass( frame ), nax ); + } + } + +/* Initialise a Frame structure (the parent class) as the first + component within the Region structure, allocating memory if + necessary. Give this Frame zero axes as the Frame information will be + specified by the encapsulated FrameSet. */ + new = (AstRegion *) astInitFrame( mem, size, 0, (AstFrameVtab *) vtab, + name, 0 ); + if ( astOK ) { + +/* Initialise the Region data. */ +/* ----------------------------- */ + new->frameset = NULL; + new->points = NULL; + new->unc = NULL; + new->meshsize = -INT_MAX; + new->adaptive = -INT_MAX; + new->basemesh = NULL; + new->basegrid = NULL; + new->negated = -INT_MAX; + new->closed = -INT_MAX; + new->regionfs = -INT_MAX; + new->fillfactor = AST__BAD; + new->defunc = NULL; + new->nomap = 0; + new->negation = NULL; + +/* If the supplied Frame is a Region, gets its encapsulated Frame. If a + FrameSet was supplied, use its current Frame, otherwise use the + supplied Frame. */ + if( astIsARegion( frame ) ) { + f0 = astGetFrame( ((AstRegion *) frame)->frameset, AST__CURRENT ); + + } else if( astIsAFrameSet( frame ) ) { + f0 = astGetFrame( (AstFrameSet *) frame, AST__CURRENT ); + + } else { + f0 = astClone( frame ); + } + +/* Store a clone of the supplied PointSet pointer. */ + new->points = pset ? astClone( pset ) : NULL; + + +#ifdef DEBUG + if( pset ) { + double **ptr; + double lim; + int ii,jj, np; + ptr = astGetPoints( pset ); + np = astGetNpoint( pset ); + lim = sqrt( DBL_MAX ); + for( ii = 0; astOK && ii < ncoord; ii++ ) { + for( jj = 0; jj < np; jj++ ) { + if( fabs( ptr[ ii ][ jj ] ) > lim ) { + if( !strcmp( name, "Interval" ) ) { + if( ptr[ ii ][ jj ] != AST__BAD && + ptr[ ii ][ jj ] != DBL_MAX && + ptr[ ii ][ jj ] != -DBL_MAX ) { + astError( AST__INTER, "astInitRegion(%s): suspicious " + "axis value (%g) supplied.", status, name, ptr[ ii ][ jj ] ); + break; + } + } else { + astError( AST__INTER, "astInitRegion(%s): suspicious " + "axis value (%g) supplied.", status, name, + ptr[ ii ][ jj ] ); + break; + } + } + } + } + } +#endif + +/* Form a FrameSet consisting of two copies of the supplied Frame connected + together by a UnitMap, and store in the Region structure. We use the + private SetRegFS rather than the protected astSetRegFS because this + initialiser may be being called from a subclass which over-rides + astSetRegFS. If this were the case, then the implementation of + astSetRegFS provided by the subclass may access information within the + subclass structure which has not yet been initialised. */ + SetRegFS( new, f0, status ); + f0 = astAnnul( f0 ); + +/* Store any uncertainty Region. Use the private SetUnc rather than + astSetUnc to avoid subclass implementations using subclass data which + has not yet been initialised. */ + SetUnc( new, unc, status ); + +/* If an error occurred, clean up by deleting the new object. */ + if ( !astOK ) new = astDelete( new ); + } + +/* Return a pointer to the new object. */ + return new; +} + +AstRegion *astLoadRegion_( void *mem, size_t size, + AstRegionVtab *vtab, const char *name, + AstChannel *channel, int *status ) { +/* +*+ +* Name: +* astLoadRegion + +* Purpose: +* Load a Region. + +* Type: +* Protected function. + +* Synopsis: +* #include "region.h" +* AstRegion *astLoadRegion( void *mem, size_t size, +* AstRegionVtab *vtab, const char *name, +* AstChannel *channel ) + +* Class Membership: +* Region loader. + +* Description: +* This function is provided to load a new Region using data read +* from a Channel. It first loads the data used by the parent class +* (which allocates memory if necessary) and then initialises a +* Region structure in this memory, using data read from the +* input Channel. + +* Parameters: +* mem +* A pointer to the memory into which the Region is to be +* loaded. This must be of sufficient size to accommodate the +* Region data (sizeof(Region)) plus any data used by +* derived classes. If a value of NULL is given, this function +* will allocate the memory itself using the "size" parameter to +* determine its size. +* size +* The amount of memory used by the Region (plus derived class +* data). This will be used to allocate memory if a value of +* NULL is given for the "mem" parameter. This value is also +* stored in the Region structure, so a valid value must be +* supplied even if not required for allocating memory. +* +* If the "vtab" parameter is NULL, the "size" value is ignored +* and sizeof(AstRegion) is used instead. +* vtab +* Pointer to the start of the virtual function table to be +* associated with the new Region. If this is NULL, a pointer +* to the (static) virtual function table for the Region class +* is used instead. +* name +* Pointer to a constant null-terminated character string which +* contains the name of the class to which the new object +* belongs (it is this pointer value that will subsequently be +* returned by the astGetClass method). +* +* If the "vtab" parameter is NULL, the "name" value is ignored +* and a pointer to the string "Region" is used instead. + +* Returned Value: +* A pointer to the new Region. + +* Notes: +* - A null pointer will be returned if this function is invoked +* with the global error status set, or if it should fail for any +* reason. +*- +*/ + +/* Local Constants: */ + astDECLARE_GLOBALS /* Pointer to thread-specific global data */ +#define KEY_LEN 50 /* Maximum length of a keyword */ + +/* Local Variables: */ + AstFrame *f1; /* Base Frame for encapsulated FrameSet */ + AstRegion *new; /* Pointer to the new Region */ + int nax; /* No. of axes in Frame, or FrameSet base Frame */ + int naxpt; /* No. of axes in per point */ + +/* Get a pointer to the thread specific global data structure. */ + astGET_GLOBALS(channel); + +/* Initialise. */ + new = NULL; + +/* Check the global error status. */ + if ( !astOK ) return new; + +/* If a NULL virtual function table has been supplied, then this is + the first loader to be invoked for this Region. In this case the + Region belongs to this class, so supply appropriate values to be + passed to the parent class loader (and its parent, etc.). */ + if ( !vtab ) { + size = sizeof( AstRegion ); + vtab = &class_vtab; + name = "Region"; + +/* If required, initialise the virtual function table for this class. */ + if ( !class_init ) { + astInitRegionVtab( vtab, name ); + class_init = 1; + } + } + +/* Invoke the parent class loader to load data for all the ancestral + classes of the current one, returning a pointer to the resulting + partly-built Region. */ + new = astLoadFrame( mem, size, (AstFrameVtab *) vtab, name, + channel ); + + if ( astOK ) { + +/* Read input data. */ +/* ================ */ +/* Request the input Channel to read all the input data appropriate to + this class into the internal "values list". */ + astReadClassData( channel, "Region" ); + +/* Now read each individual data item from this list and use it to + initialise the appropriate instance variable(s) for this class. */ + +/* In the case of attributes, we first read the "raw" input value, + supplying the "unset" value as the default. If a "set" value is + obtained, we then use the appropriate (private) Set... member + function to validate and set the value properly. */ + +/* Negated */ +/* ------- */ + new->negated = astReadInt( channel, "negate", -INT_MAX ); + if ( TestNegated( new, status ) ) SetNegated( new, new->negated, status ); + +/* FillFactor */ +/* ---------- */ + new->fillfactor = astReadDouble( channel, "fill", AST__BAD ); + if ( TestFillFactor( new, status ) ) SetFillFactor( new, new->fillfactor, status ); + +/* MeshSize */ +/* -------- */ + new->meshsize = astReadInt( channel, "meshsz", -INT_MAX ); + if ( TestMeshSize( new, status ) ) SetMeshSize( new, new->meshsize, status ); + +/* Closed */ +/* ------ */ + new->closed = astReadInt( channel, "closed", -INT_MAX ); + if ( TestClosed( new, status ) ) SetClosed( new, new->closed, status ); + +/* Adaptive */ +/* -------- */ + new->adaptive = astReadInt( channel, "adapt", -INT_MAX ); + if ( TestAdaptive( new, status ) ) SetAdaptive( new, new->adaptive, status ); + +/* Points */ +/* ------ */ + new->points = astReadObject( channel, "points", NULL ); + +/* If some points were found, ensure that they are in a PointSet and get + the number of axis values per point. */ + if( new->points ){ + if( astIsAPointSet( new->points) ) { + naxpt = astGetNcoord( new->points ); + } else { + naxpt = 0; + astError( AST__REGIN, "astLoadRegion(%s): Corrupt %s specifies points " + "using a %s (should be a PointSet).", status, astGetClass( new ), + astGetClass( new ), astGetClass( new->points ) ); + } + +/* If no PointSet was loaded, attempt to determine the number of axes + spanned by the Region by reading the RegAxes value. */ + } else { + naxpt = astReadInt( channel, "regaxes", 0 ); + } + +/* Uncertainty */ +/* ----------- */ + new->unc = astReadObject( channel, "unc", NULL ); + new->defunc = NULL; + +/* FrameSet */ +/* -------- */ +/* First see if the dump contains a single Frame. If so, create a + FrameSet from it and a copy of itself, using a UnitMap to connect the + two. */ + new->nomap = 0; + new->frameset = NULL; + f1 = astReadObject( channel, "frm", NULL ); + if( f1 ) { + new->regionfs = 1; + nax = astGetNaxes( f1 ); + astSetRegFS( new, f1 ); + f1 = astAnnul( f1 ); + +/* If no Frame was found in the dump, look for a FrameSet. Get the number + of axes spanning its base Frame ("Nin"). */ + } else { + new->frameset = astReadObject( channel, "frmset", NULL ); + if( new->frameset ) { + nax = astGetNin( new->frameset ); + +/* If a FrameSet was found, the value of the RegionFS attribute is still + unknown and so we must read it from an attribute as normal. */ + new->regionfs = astReadInt( channel, "regfs", 1 ); + if ( TestRegionFS( new, status ) ) SetRegionFS( new, new->regionfs, status ); + + } else { + nax = 0; + } + } + +/* If neither a Frame nor a FrameSet was found, create a default FrameSet + and set the RegionFS attribute false, to indicate that the FrameSet + should not be used. */ + if( !new->frameset ){ + nax = naxpt ? naxpt : 1; + f1 = astFrame( nax, "", status ); + new->frameset = astFrameSet( f1, "", status ); + astSetIdent( new->frameset, DUMMY_FS ); + f1 = astAnnul( f1 ); + new->regionfs = 0; + } + +/* Report an error if the number of axis values per point in the pointset is + incorrect. */ + if ( astOK && new->points && ( naxpt != nax ) ) { + astError( AST__REGIN, "astLoadRegion(%s): Corrupt %s contains " + " incorrect number of coordinate values per point (%d).", status, + astGetClass( new ), astGetClass( new ), naxpt ); + astError( AST__REGIN, "The %s requires %d coordinate value(s) " + "for each point.", status, astGetClass( new ), nax ); + } + +/* Initialise other fields which are used as caches for values derived + from the attributes set above. */ + new->basemesh = NULL; + new->basegrid = NULL; + +/* If an error occurred, clean up by deleting the new Region. */ + if ( !astOK ) new = astDelete( new ); + } + +/* Return the new Region pointer. */ + return new; + +/* Undefine macros local to this function. */ +#undef KEY_LEN +} + +/* Virtual function interfaces. */ +/* ============================ */ +/* These provide the external interface to the virtual functions defined by + this class. Each simply checks the global error status and then locates and + executes the appropriate member function, using the function pointer stored + in the object's virtual function table (this pointer is located using the + astMEMBER macro defined in "object.h"). + + Note that the member function may not be the one defined here, as it may + have been over-ridden by a derived class. However, it should still have the + same interface. */ + +void astRegClearAttrib_( AstRegion *this, const char *attrib, char **base_attrib, int *status ) { + if ( !astOK ) return; + (**astMEMBER(this,Region,RegClearAttrib))( this, attrib, base_attrib, status ); +} +void astRegSetAttrib_( AstRegion *this, const char *setting, char **base_setting, int *status ) { + if ( !astOK ) return; + (**astMEMBER(this,Region,RegSetAttrib))( this, setting, base_setting, status ); +} +void astNegate_( AstRegion *this, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,Negate))( this, status ); +} +AstFrame *astGetRegionFrame_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,GetRegionFrame))( this, status ); +} +AstFrameSet *astGetRegionFrameSet_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,GetRegionFrameSet))( this, status ); +} +AstRegion *astMapRegion_( AstRegion *this, AstMapping *map, AstFrame *frame, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,MapRegion))( this, map, frame, status ); +} +int astOverlap_( AstRegion *this, AstRegion *that, int *status ){ + if ( !astOK ) return 0; + return (**astMEMBER(this,Region,Overlap))( this, that, status ); +} +int astOverlapX_( AstRegion *that, AstRegion *this, int *status ){ + if ( !astOK ) return 0; + return (**astMEMBER(that,Region,OverlapX))( that, this, status ); +} +AstFrame *astRegFrame_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegFrame))( this, status ); +} +AstRegion *astRegBasePick_( AstRegion *this, int naxes, const int *axes, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegBasePick))( this, naxes, axes, status ); +} +AstPointSet *astBTransform_( AstRegion *this, AstPointSet *in, + int forward, AstPointSet *out, int *status ) { + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,BTransform))( this, in, forward, out, status ); +} +AstPointSet *astRegTransform_( AstRegion *this, AstPointSet *in, + int forward, AstPointSet *out, + AstFrame **frm, int *status ) { + if( frm ) *frm = NULL; + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegTransform))( this, in, forward, out, frm, status ); +} +int astRegPins_( AstRegion *this, AstPointSet *pset, AstRegion *unc, int **mask, int *status ){ + if( mask ) *mask = NULL; + if ( !astOK ) return 0; + return (**astMEMBER(this,Region,RegPins))( this, pset, unc, mask, status ); +} +AstMapping *astRegMapping_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegMapping))( this, status ); +} +int astRegDummyFS_( AstRegion *this, int *status ){ + if ( !astOK ) return 0; + return (**astMEMBER(this,Region,RegDummyFS))( this, status ); +} +int astGetBounded_( AstRegion *this, int *status ){ + if ( !astOK ) return 0; + return (**astMEMBER(this,Region,GetBounded))( this, status ); +} +int astTestUnc_( AstRegion *this, int *status ){ + if ( !astOK ) return 0; + return (**astMEMBER(this,Region,TestUnc))( this, status ); +} +void astClearUnc_( AstRegion *this, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,ClearUnc))( this, status ); +} +void astRegBaseBox_( AstRegion *this, double *lbnd, double *ubnd, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,RegBaseBox))( this, lbnd, ubnd, status ); +} +void astRegBaseBox2_( AstRegion *this, double *lbnd, double *ubnd, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,RegBaseBox2))( this, lbnd, ubnd, status ); +} +void astResetCache_( AstRegion *this, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,ResetCache))( this, status ); +} +int astRegTrace_( AstRegion *this, int n, double *dist, double **ptr, int *status ){ + if ( !astOK ) return 0; + return (**astMEMBER(this,Region,RegTrace))( this, n, dist, ptr, status ); +} +void astGetRegionBounds_( AstRegion *this, double *lbnd, double *ubnd, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,GetRegionBounds))( this, lbnd, ubnd, status ); +} +void astGetRegionMesh_( AstRegion *this, int surface, int maxpoint, + int maxcoord, int *npoint, double *points, + int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,GetRegionMesh))( this, surface, maxpoint, maxcoord, + npoint, points, status ); +} +void astGetRegionPoints_( AstRegion *this, int maxpoint, int maxcoord, + int *npoint, double *points, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,GetRegionPoints))( this, maxpoint, maxcoord, + npoint, points, status ); +} +void astShowMesh_( AstRegion *this, int format, const char *ttl, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,ShowMesh))( this, format,ttl, status ); +} +void astGetRegionBounds2_( AstRegion *this, double *lbnd, double *ubnd, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,GetRegionBounds2))( this, lbnd, ubnd, status ); +} +void astRegOverlay_( AstRegion *this, AstRegion *that, int unc, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,RegOverlay))( this, that, unc, status ); +} +AstPointSet *astRegGrid_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegGrid))( this, status ); +} +AstPointSet *astRegMesh_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegMesh))( this, status ); +} +double *astRegCentre_( AstRegion *this, double *cen, double **ptr, int index, + int ifrm, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegCentre))( this, cen, ptr, index, ifrm, status ); +} +AstRegion *astGetNegation_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,GetNegation))( this, status ); +} +AstRegion *astGetUncFrm_( AstRegion *this, int ifrm, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,GetUncFrm))( this, ifrm, status ); +} +AstRegion *astGetDefUnc_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,GetDefUnc))( this, status ); +} +AstRegion *astGetUnc_( AstRegion *this, int def, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,GetUnc))( this, def, status ); +} +void astSetUnc_( AstRegion *this, AstRegion *unc, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,SetUnc))( this, unc, status ); +} +AstFrameSet *astGetRegFS_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,GetRegFS))( this, status ); +} +void astSetRegFS_( AstRegion *this, AstFrame *frm, int *status ){ + if ( !astOK ) return; + (**astMEMBER(this,Region,SetRegFS))( this, frm, status ); +} +AstPointSet *astRegBaseMesh_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegBaseMesh))( this, status ); +} +AstRegion **astRegSplit_( AstRegion *this, int *nlist, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegSplit))( this, nlist, status ); +} +AstPointSet *astRegBaseGrid_( AstRegion *this, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,RegBaseGrid))( this, status ); +} +AstPointSet *astBndBaseMesh_( AstRegion *this, double *lbnd, double *ubnd, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,BndBaseMesh))( this, lbnd, ubnd, status ); +} +AstPointSet *astBndMesh_( AstRegion *this, double *lbnd, double *ubnd, int *status ){ + if ( !astOK ) return NULL; + return (**astMEMBER(this,Region,BndMesh))( this, lbnd, ubnd, status ); +} + +#define MAKE_MASK_(X,Xtype) \ +int astMask##X##_( AstRegion *this, AstMapping *map, int inside, int ndim, \ + const int lbnd[], const int ubnd[], Xtype in[], \ + Xtype val, int *status ) { \ + if ( !astOK ) return 0; \ + return (**astMEMBER(this,Region,Mask##X))( this, map, inside, ndim, lbnd, \ + ubnd, in, val, status ); \ +} +#if HAVE_LONG_DOUBLE /* Not normally implemented */ +MAKE_MASK_(LD,long double) +#endif +MAKE_MASK_(D,double) +MAKE_MASK_(F,float) +MAKE_MASK_(L,long int) +MAKE_MASK_(UL,unsigned long int) +MAKE_MASK_(I,int) +MAKE_MASK_(UI,unsigned int) +MAKE_MASK_(S,short int) +MAKE_MASK_(US,unsigned short int) +MAKE_MASK_(B,signed char) +MAKE_MASK_(UB,unsigned char) +#undef MAKE_MASK_ + +/* Special public interface functions. */ +/* =================================== */ +/* These provide the public interface to certain special functions + whose public interface cannot be handled using macros (such as + astINVOKE) alone. In general, they are named after the + corresponding protected version of the function, but with "Id" + appended to the name. */ + +/* Public Interface Function Prototypes. */ +/* ------------------------------------- */ +/* The following functions have public prototypes only (i.e. no + protected prototypes), so we must provide local prototypes for use + within this module. */ + +/* Special interface function implementations. */ +/* ------------------------------------------- */ + + +AstRegion *astMapRegionId_( AstRegion *this, AstMapping *map, AstFrame *frame, int *status ) { +/* +*++ +* Name: +c astMapRegion +f AST_MAPREGION + +* Purpose: +* Transform a Region into a new Frame using a given Mapping. + +* Type: +* Public virtual function. + +* Synopsis: +c #include "region.h" +c AstRegion *astMapRegion( AstRegion *this, AstMapping *map, +c AstFrame *frame ) +f RESULT = AST_MAPREGION( THIS, MAP, FRAME, STATUS ) + +* Class Membership: +* Region method. + +* Description: +* This function returns a pointer to a new Region which corresponds to +* supplied Region described by some other specified coordinate system. A +* Mapping is supplied which transforms positions between the old and new +* coordinate systems. The new Region may not be of the same class as +* the original region. + +* Parameters: +c this +f THIS = INTEGER (Given) +* Pointer to the Region. +c map +f MAP = INTEGER (Given) +* Pointer to a Mapping which transforms positions from the +* coordinate system represented by the supplied Region to the +* coordinate system specified by +c "frame". +f FRAME. +* The supplied Mapping should define both forward and inverse +* transformations, and these transformations should form a genuine +* inverse pair. That is, transforming a position using the forward +* transformation and then using the inverse transformation should +* produce the original input position. Some Mapping classes (such +* as PermMap, MathMap, SphMap) can result in Mappings for which this +* is not true. +c frame +f FRAME = INTEGER (Given) +* Pointer to a Frame describing the coordinate system in which +* the new Region is required. +f STATUS = INTEGER (Given and Returned) +f The global status. + +* Returned Value: +c astMapRegion() +f AST_MAPREGION = INTEGER +* A pointer to a new Region. This Region will represent the area +* within the coordinate system specified by +c "frame" +f FRAME +* which corresponds to the supplied Region. + +* Notes: +* - The uncertainty associated with the supplied Region is modified +* using the supplied Mapping. +* - A null Object pointer (AST__NULL) will be returned if this +c function is invoked with the AST error status set, or if it +f function is invoked with STATUS set to an error value, or if it +* should fail for any reason. +*-- + +* Implementation Notes: +* - The only difference between this public interface and the protected +* astMapRegion interface is that this implementation additionally +* simplifies the returned Region. The protected implementation does +* not do this since doing so can lead to infinite recursion because +* it is sometimes necessary for Simplify to call astMapRegion. + +*/ + +/* Local Variables: */ + AstRegion *new; /* Pointer to new Region */ + AstRegion *result; /* Pointer value to return */ + +/* Initialise. */ + result = NULL; + +/* Check the global error status. */ + if ( !astOK ) return result; + +/* Invoke the protected astMapRegion function. */ + new = astMapRegion( this, map, frame ); + +/* Simplify the resulting Region. */ + result = astSimplify( new ); + +/* Free resources. */ + new = astAnnul( new ); + +/* If not OK, annul the returned pointer. */ + if( !astOK ) result = astAnnul( result ); + +/* Return the result. */ + return result; +} + + + + + + + + + + + + |