diff options
Diffstat (limited to 'ast/frame.c')
| -rw-r--r-- | ast/frame.c | 16067 |
1 files changed, 0 insertions, 16067 deletions
diff --git a/ast/frame.c b/ast/frame.c deleted file mode 100644 index bd70cdd..0000000 --- a/ast/frame.c +++ /dev/null @@ -1,16067 +0,0 @@ -/* -*class++ -* Name: -* Frame - -* Purpose: -* Coordinate system description. - -* Constructor Function: -c astFrame -f AST_FRAME - -* Description: -* This class is used to represent coordinate systems. It does this -* in rather the same way that a frame around a graph describes the -* coordinate space in which data are plotted. Consequently, a -* Frame has a Title (string) attribute, which describes the -* coordinate space, and contains axes which in turn hold -* information such as Label and Units strings which are used for -* labelling (e.g.) graphical output. In general, however, the -* number of axes is not restricted to two. -* -* Functions are available for converting Frame coordinate values -* into a form suitable for display, and also for calculating -* distances and offsets between positions within the Frame. -* -* Frames may also contain knowledge of how to transform to and -* from related coordinate systems. - -* Inheritance: -* The Frame class inherits from the Mapping class. - -* Attributes: -* In addition to those attributes common to all Mappings, every -* Frame also has the following attributes (if the Frame has only one -* axis, the axis specifier can be omited from the following attribute -* names): -* -* - AlignSystem: Coordinate system used to align Frames -* - Bottom(axis): Lowest axis value to display -* - Digits/Digits(axis): Number of digits of precision -* - Direction(axis): Display axis in conventional direction? -* - Domain: Coordinate system domain -* - Dtai: Difference between the TAI and UTC timescale -* - Dut1: Difference between the UT1 and UTC timescale -* - Epoch: Epoch of observation -* - Format(axis): Format specification for axis values -* - InternalUnit(axis): Physical units for unformated axis values -* - Label(axis): Axis label -* - MatchEnd: Match trailing axes? -* - MaxAxes: Maximum number of Frame axes to match -* - MinAxes: Minimum number of Frame axes to match -* - Naxes: Number of Frame axes -* - NormUnit(axis): Normalised physical units for formatted axis values -* - ObsAlt: Geodetic altitude of observer -* - ObsLat: Geodetic latitude of observer -* - ObsLon: Geodetic longitude of observer -* - Permute: Permute axis order? -* - PreserveAxes: Preserve axes? -* - Symbol(axis): Axis symbol -* - System: Coordinate system used to describe the domain -* - Title: Frame title -* - Top(axis): Highest axis value to display -* - Unit(axis): Physical units for formatted axis values - -* Functions: -c In addition to those functions applicable to all Mappings, the -c following functions may also be applied to all Frames: -f In addition to those routines applicable to all Mappings, the -f following routines may also be applied to all Frames: -* -c - astAngle: Calculate the angle subtended by two points at a third point -c - astAxAngle: Find the angle from an axis, to a line through two points -c - astAxDistance: Calculate the distance between two axis values -c - astAxNorm: Normalises an array of axis values -c - astAxOffset: Calculate an offset along an axis -c - astConvert: Determine how to convert between two coordinate systems -c - astDistance: Calculate the distance between two points in a Frame -c - astFindFrame: Find a coordinate system with specified characteristics -c - astFormat: Format a coordinate value for a Frame axis -c - astGetActiveUnit: Determines how the Unit attribute will be used -c - astIntersect: Find the intersection between two geodesic curves -c - astMatchAxes: Find any corresponding axes in two Frames -c - astNorm: Normalise a set of Frame coordinates -c - astOffset: Calculate an offset along a geodesic curve -c - astOffset2: Calculate an offset along a geodesic curve in a 2D Frame -c - astPermAxes: Permute the order of a Frame's axes -c - astPickAxes: Create a new Frame by picking axes from an existing one -c - astResolve: Resolve a vector into two orthogonal components -c - astSetActiveUnit: Specify how the Unit attribute should be used -c - astUnformat: Read a formatted coordinate value for a Frame axis -f - AST_ANGLE: Find the angle subtended by two points at a third point -f - AST_AXANGLE: Find the angle from an axis, to a line through two points -f - AST_AXDISTANCE: Calculate the distance between two axis values -f - AST_AXNORM: Normalises an array of axis values -f - AST_AXOFFSET: Calculate an offset along an axis -f - AST_CONVERT: Determine how to convert between two coordinate systems -f - AST_DISTANCE: Calculate the distance between two points in a Frame -f - AST_FINDFRAME: Find a coordinate system with specified characteristics -f - AST_FORMAT: Format a coordinate value for a Frame axis -f - AST_GETACTIVEUNIT: Determines how the Unit attribute will be used -f - AST_INTERSECT: Find the intersection between two geodesic curves -f - AST_MATCHAXES: Find any corresponding axes in two Frames -f - AST_NORM: Normalise a set of Frame coordinates -f - AST_OFFSET: Calculate an offset along a geodesic curve -f - AST_OFFSET2: Calculate an offset along a geodesic curve in a 2D Frame -f - AST_PERMAXES: Permute the order of a Frame's axes -f - AST_PICKAXES: Create a new Frame by picking axes from an existing one -f - AST_RESOLVE: Resolve a vector into two orthogonal components -f - AST_SETACTIVEUNIT: Specify how the Unit attribute should be used -f - AST_UNFORMAT: Read a formatted coordinate value for a Frame axis - -* Notes: -* - When used as a Mapping, a Frame implements a unit (null) -* transformation in both the forward and inverse directions -* (equivalent to a UnitMap). The Nin and Nout attribute values are -* both equal to the number of Frame axes. - -* Copyright: -* Copyright (C) 1997-2006 Council for the Central Laboratory of the -* Research Councils - -* 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: -* RFWS: R.F. Warren-Smith (Starlink) -* DSB: B.S. Berry (Starlink) - -* History: -* 1-MAR-1996 (RFWS): -* Original version. -* 4-JUN-1996 (RFWS): -* Added the CleanDomain function to fold all Domain strings to -* upper case and remove white space. -* 12-JUL-1996 (RFWS): -* Over-ride the astReportPoints method to provide -* Frame-specific formatting. -* 11-SEP-1996 (RFWS): -* Added astGap (written by DSB). -* 10-JUN-1997 (RFWS): -* Re-implemented astConvert and astFindFrame. -* 1-SEP-1997 (RFWS): -* Added missing return statement in astAbbrev_. -* 14-NOV-1997 (RFWS): -* Fixed wrong amount of memory allocated in ValidateAxisSelection. -* 20-NOV-1997 (RFWS): -* Updated astConvert prologue. -* 22-DEC-1997 (RFWS): -* Updated astConvert prologue again. -* 15-FEB-1998 (RFWS): -* Added astUnformat. -* 2-MAR-1999 (RFWS); -* Fixed missing STATUS arguments in examples for AST_FINDFRAME -* prologue. -* 18-JUL-1999 (RFWS): -* Fixed memory leak in ConvertX. -* 21-JUN-2001 (DSB): -* Added methods astAngle and astOffset2. -* 29-AUG-2001 (DSB): -* Added methods astAxDistance and astAxOffset. -* 4-SEP-2001 (DSB): -* Added method astResolve. -* 9-SEP-2001 (DSB): -* Added method astBear. -* 21-SEP-2001 (DSB): -* Replaced astBear with astAxAngle. -* 10-OCT-2002 (DSB): -* Added Top and Bottom. -* 15-NOV-2002 (DSB): -* Moved the System and Epoch attributes from the SkyFrame class to -* this class. Added virtual method astValidateSystem, astSystemString, -* astSystemCode. Added attribute AlignSystem. -* 17-DEC-2002 (DSB): -* Added the GetActiveUnit, TestActiveUnit and SetActiveUnit functions. -* 8-JAN-2003 (DSB): -* Changed private InitVtab method to protected astInitFrameVtab -* method. -* 15-SEP-2003 (DSB): -* Allow Frame attribute names to include an axis specifier within -* GetAttrib, SetAttrib, TestAttrib and ClearAttrib (eg "Domain(1)" -* is now accepted as equivalent to "Domain"). -* 24-JAN-2004 (DSB): -* o Added astFields. -* o Added argument "fmt" to Abbrev. -* 24-MAR-2004 (DSB): -* Add protected function astIsUnitFrame. -* 7-SEP-2004 (DSB): -* Modified SetUnit to exclude any trailing spaces -* 8-SEP-2004 (DSB): -* - Added astResolvePoints. -* - Override astEqual. -* 29-NOV-2004 (DSB): -* - Set/Get/Test/ClearAttrib: Allow axis specifier to be omitted from -* axis attribute names if the Frame only has one axis. -* 2-FEB-2005 (DSB): -* - Avoid using astStore to allocate more storage than is supplied -* in the "data" pointer. This can cause access violations since -* astStore will then read beyond the end of the "data" area. -* 17-FEB-2005 (DSB): -* - Change use of ActiveUnit flag so that both target and template -* Frames must have active units in order for the Mapping to take -* account of differences in units. Previously, the test was based -* on the template Frame alone. -* 23-MAR-2005 (DSB): -* - GetActiveUnit: Always return zero if the Frame contains any -* SkyAxes. -* 5-APR-2005 (DSB): -* Correct error checking in Clear/Get/Set/TestAttrib. -* 12-MAY-2005 (DSB): -* Added astNormBox method. -* 16-JUN-2005 (DSB): -* Added documentation for the TimeFrame class. -* 12-AUG-2005 (DSB): -* Added ObsLat and ObsLon attributes. -* 1-MAR-2006 (DSB): -* Replace astSetPermMap within DEBUG blocks by astBeginPM/astEndPM. -* 15-MAY-2006 (DSB): -* Remove unused global variable parent_equal. -* 26-JUN-2006 (DSB): -* Document the use of the Direction attribute by the Plot class. -* 30-JUN-2006 (DSB): -* Allow astAbbrev to have a null "str1" value. -* 16-AUG-2006 (DSB): -* Correct "Class Applicability" to "Applicability". -* 5-OCT-2006 (DSB): -* Increase the number of digits used when formating a ObsLon or -* ObsLat value in GetAttrib. -* 14-OCT-2006 (DSB): -* - Add Dut1 attribute -* 26-JAN-2007 (DSB): -* Fix bug in NewUnit that causes segvio when changing axis symbols -* to accomodate changes in units. -* 17-MAY-2007 (DSB): -* Added read-only attribute NormUnit. -* 21-MAY-2007 (DSB): -* Use rather than ignore the value returned by astTestAxisDigits in -* TestAttrib. -* 25-JUN-2007 (DSB): -* Documentation typos. -* 26-NOV-2007 (DSB): -* In Clear/Get/Set/TestAttrib, include any appropriate axis index in -* the attribute name when attempting to get the attribute value from -* the primary frame -* 17-NOV-2008 (DSB): -* Correct parent class in invocation of astMAKE_ISA. -* 14-JAN-2009 (DSB): -* Added astIntersect. -* 18-MAR-2009 (DSB): -* Fixed bug in LineCrossing. -* 18-JUN-2000 (DSB): -* Added ObsAlt attribute. -* 28-SEP-2009 (DSB): -* Added astMatchAxes method. -* 22-MAR-2011 (DSB): -* Add astFrameGrid method. -* 29-APR-2011 (DSB): -* Prevent astFindFrame from matching a subclass template against a -* superclass target. -* 11-APR-2012 (DSB): -* Change astValidateAxis so that it can permute in either direction. -* 29-APR-2013 (DSB): -* Added protected methods astSetFrameVariants and astGetFrameVariants. -* 1-MAY-2013 (DSB): -* Override the astDoNotSimplify method to indicate that Frames should -* always be simplified. This is mainly because the STC class uses the -* Ident attribute with Frames, and preventing such frames from -* simplifying (which is what the parent astDoNotSimplify method does) -* causes the STC tester in the ast_tester directory to fail. -* 10-FEB-2015 (DSB): -* When checking attribute settings for attribute names that end with -* an axis index, stop looking for the axis index when the first equals -* sign is encountered. -* 17-APR-2015 (DSB): -* Added astCentre. -* 27-APR-2015 (DSB): -* Added read-only attribute InternalUnit. -* 26-OCT-2016 (DSB): -* Added method astAxNorm. -* 11-JAN-2017 (GSB): -* Add Dtai attribute. -*class-- -*/ - -/* 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 Frame - -/* Define numerical constants for use in this module. */ -#define LABEL_BUFF_LEN 100 /* Max length of default axis Label string */ -#define SYMBOL_BUFF_LEN 50 /* Max length of default axis Symbol string */ -#define TITLE_BUFF_LEN 100 /* Max length of default title string */ -#define GETATTRIB_BUFF_LEN 50 /* Max length of string returned by GetAttrib */ -#define ASTFMTDECIMALYR_BUFF_LEN 50 /* Max length of string returned by GetAttrib */ -#define ASTFORMATID_MAX_STRINGS 50 /* Number of string values buffer by astFormatID*/ - - -/* Define the first and last acceptable System values. */ -#define FIRST_SYSTEM AST__CART -#define LAST_SYSTEM AST__CART - -/* Define macros to implement methods for accessing axis attributes. */ -/* -* Name: -* MAKE_CLEAR - -* Purpose: -* Implement a method to clear an attribute value for a Frame axis. - -* Type: -* Private macro. - -* Synopsis: -* #include "frame.h" -* MAKE_CLEAR(attribute) - -* Class Membership: -* Defined by the Frame class. - -* Description: -* This macro expands to an implementation of a private member function of -* the form: -* -* static void Clear<Attribute>( AstFrame *this, int axis ) -* -* and an external interface function of the form: -* -* void astClear<Attribute>_( AstFrame *this, int axis ) -* -* which implement a method for clearing an attribute value for a specified -* axis of a Frame. - -* Parameters: -* attribute -* The name of the attribute to be cleared, as it appears in the -* function name (e.g. Label in "astClearLabel"). - -* Notes: -* - This macro assumes the existence of a method of the form: -* -* void astClearAxis<Attribute>( AstAxis *this ) -* -* which clears the required attribute for an Axis object. -* - To avoid problems with some compilers, you should not leave any white -* space around the macro arguments. -*/ - -/* Define the macro. */ -#define MAKE_CLEAR(attribute) \ -\ -/* Private member function. */ \ -/* ------------------------ */ \ -static void Clear##attribute( AstFrame *this, int axis, int *status ) { \ - AstAxis *ax; /* Pointer to Axis object */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return; \ -\ -/* Validate the axis index and obtain a pointer to the required Axis. */ \ - (void) astValidateAxis( this, axis, 1, "astClear" #attribute ); \ - ax = astGetAxis( this, axis ); \ -\ -/* Clear the Axis attribute. */ \ - astClearAxis##attribute( ax ); \ -\ -/* Annul the Axis pointer. */ \ - ax = astAnnul( ax ); \ -} \ -\ -/* External interface. */ \ -/* ------------------- */ \ -void astClear##attribute##_( AstFrame *this, int axis, int *status ) { \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return; \ -\ -/* Invoke the required method via the virtual function table. */ \ - (**astMEMBER(this,Frame,Clear##attribute))( this, axis, status ); \ -} - -/* -* Name: -* MAKE_GET - -* Purpose: -* Implement a method to get an attribute value for a Frame axis. - -* Type: -* Private macro. - -* Synopsis: -# #include "frame.h" -* MAKE_GET(attribute,type,bad_value,default,assign_default) - -* Class Membership: -* Defined by the Frame class. - -* Description: -* This macro expands to an implementation of a private member function of -* the form: -* -* static <Type> Get<Attribute>( AstFrame *this, int axis ) -* -* and an external interface function of the form: -* -* Type astGet<Attribute>_( AstFrame *this, int axis ) -* -* which implement a method for getting an attribute value for a specified -* axis of a Frame. - -* Parameters: -* attribute -* The name of the attribute whose value is to be obtained, as -* it appears in the function name (e.g. Label in -* "astGetLabel"). -* type -* The C type of the attribute. -* bad_value -* A constant value to return if the global error status is set, or if -* the function fails. -* default -* A boolean (int) constant that indicates whether a new default value -* should be returned by the method if the requested attribute has not -* been set for the axis. If this value is zero, the axis default will -* be used instead. -* assign_default -* An expression that evaluates to the new default value to be assigned. -* This value is ignored if "default" is zero, but a valid (e.g. -* constant) value should nevertheless be supplied. - -* Notes: -* - This macro assumes the existence of a method of the form: -* -* <Type> astGetAxis<Attribute>( AstAxis *this ) -* -* which gets the required attribute for an Axis object. -* - To avoid problems with some compilers, you should not leave any white -* space around the macro arguments. -*/ - -/* Define the macro. */ -#define MAKE_GET(attribute,type,bad_value,default,assign_default) \ -\ -/* Private member function. */ \ -/* ------------------------ */ \ -static type Get##attribute( AstFrame *this, int axis, int *status ) { \ - AstAxis *ax; /* Pointer to Axis object */ \ - int digits_set; /* Axis Digits attribute set? */ \ - int old_axis; /* Original (un-permuted) axis index */ \ - type result; /* Result to be returned */ \ -\ -/* Initialise. */ \ - result = (bad_value); \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return result; \ -\ -/* Validate and permute the axis index and obtain a pointer to the required \ - Axis. */ \ - old_axis = axis; \ - axis = astValidateAxis( this, axis, 1, "astGet" #attribute ); \ - ax = astGetAxis( this, old_axis ); \ -\ -/* Since the Axis is "managed" by the enclosing Frame, we next test if any \ - Axis attributes which may affect the result are undefined (i.e. have not \ - been explicitly set). If so, we over-ride them, giving them temporary \ - values dictated by the Frame. Only the Digits attribute is relevant \ - here. */ \ - digits_set = astTestAxisDigits( ax ); \ - if ( !digits_set ) astSetAxisDigits( ax, astGetDigits( this ) ); \ -\ -/* If the default value is to be over-ridden, test if the Axis attribute has \ - been set. Then, if required, obtain the attribute value from the Axis. */ \ - if ( !(default) || astTestAxis##attribute( ax ) ) { \ - result = astGetAxis##attribute( ax ); \ -\ -/* If required, assign the new default value. */ \ - } else { \ - result = (assign_default); \ - } \ -\ -/* Clear Axis attributes which were temporarily over-ridden above and annul \ - the Axis pointer. */ \ - if ( !digits_set ) astClearAxisDigits( ax ); \ - ax = astAnnul( ax ); \ -\ -/* If an error occurred, clear the result value. */ \ - if ( !astOK ) result = (bad_value); \ -\ -/* Return the result. */ \ - return result; \ -} \ -\ -/* External interface. */ \ -/* ------------------- */ \ -type astGet##attribute##_( AstFrame *this, int axis, int *status ) { \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return (bad_value); \ -\ -/* Invoke the required method via the virtual function table. */ \ - return (**astMEMBER(this,Frame,Get##attribute))( this, axis, status ); \ -} - -/* -* Name: -* MAKE_SET - -* Purpose: -* Implement a method to set an attribute value for a Frame axis. - -* Type: -* Private macro. - -* Synopsis: -* #include "frame.h" -* MAKE_SET(attribute,type) - -* Class Membership: -* Defined by the Frame 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 ) -* -* and an external interface function of the form: -* -* void astSet<Attribute>_( AstFrame *this, int axis, <Type> value ) -* -* which implement a method for setting an attribute value for a specified -* axis of a Frame. - -* Parameters: -* attribute -* The name of the attribute to be set, as it appears in the -* function name (e.g. Label in "astSetLabel"). -* type -* The C type of the attribute. - -* Notes: -* - This macro assumes the existence of a method of the form: -* -* void astSetAxis<Attribute>( AstAxis *this, <Type> value ) -* -* which sets the required attribute for an Axis object. -* - To avoid problems with some compilers, you should not leave any white -* space around the macro arguments. -*/ - -/* Define the macro. */ -#define MAKE_SET(attribute,type) \ -\ -/* Private member function. */ \ -/* ------------------------ */ \ -static void Set##attribute( AstFrame *this, int axis, type value, int *status ) { \ - AstAxis *ax; /* Pointer to Axis object */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return; \ -\ -/* Validate the axis index and obtain a pointer to the required Axis. */ \ - (void) astValidateAxis( this, axis, 1, "astSet" #attribute ); \ - ax = astGetAxis( this, axis ); \ -\ -/* Set the Axis attribute value. */ \ - astSetAxis##attribute( ax, value ); \ -\ -/* Annul the Axis pointer. */ \ - ax = astAnnul( ax ); \ -} \ -\ -/* External interface. */ \ -/* ------------------- */ \ -void astSet##attribute##_( AstFrame *this, int axis, type value, int *status ) { \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return; \ -\ -/* Invoke the required method via the virtual function table. */ \ - (**astMEMBER(this,Frame,Set##attribute))( this, axis, value, status ); \ -} - -/* -* Name: -* MAKE_TEST - -* Purpose: -* Implement a method to test if an attribute has been set for a Frame axis. - -* Type: -* Private macro. - -* Synopsis: -* #include "frame.h" -* MAKE_TEST(attribute) - -* Class Membership: -* Defined by the Frame class. - -* Description: -* This macro expands to an implementation of a private member function of -* the form: -* -* static int Test<Attribute>( AstFrame *this, int axis ) -* -* and an external interface function of the form: -* -* int astTest<Attribute>_( AstFrame *this, int axis ) -* -* which implement a method for testing if an attribute has been set for a -* specified axis of a Frame. - -* Parameters: -* attribute -* The name of the attribute to be tested, as it appears in the -* function name (e.g. Label in "astTestLabel"). - -* Notes: -* - This macro assumes the existence of a method of the form: -* -* void astTestAxis<Attribute>( AstAxis *this ) -* -* which tests the required attribute for an Axis object. -* - To avoid problems with some compilers, you should not leave any white -* space around the macro arguments. -*/ - -/* Define the macro. */ -#define MAKE_TEST(attribute) \ -\ -/* Private member function. */ \ -/* ------------------------ */ \ -static int Test##attribute( AstFrame *this, int axis, int *status ) { \ - AstAxis *ax; /* Pointer to Axis object */ \ - int result; /* Value to be returned */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return 0; \ -\ -/* Validate the axis index and obtain a pointer to the required Axis. */ \ - (void) astValidateAxis( this, axis, 1, "astTest" #attribute ); \ - ax = astGetAxis( this, axis ); \ -\ -/* Test if the attribute has been set. */ \ - result = astTestAxis##attribute( ax ); \ -\ -/* Annul the Axis pointer. */ \ - ax = astAnnul( ax ); \ -\ -/* If an error occurred, clear the result value. */ \ - if ( !astOK ) result = 0; \ -\ -/* Return the result. */ \ - return result; \ -} \ -\ -/* External interface. */ \ -/* ------------------- */ \ -int astTest##attribute##_( AstFrame *this, int axis, int *status ) { \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return 0; \ -\ -/* Invoke the required method via the virtual function table. */ \ - return (**astMEMBER(this,Frame,Test##attribute))( this, axis, status ); \ -} - -/* 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 (parent class) */ -#include "pointset.h" /* Sets of points */ -#include "unitmap.h" /* Unit Mapping */ -#include "permmap.h" /* Coordinate permutation Mapping */ -#include "cmpmap.h" /* Compound Mappings */ -#include "axis.h" /* Coordinate Axis */ -#include "skyaxis.h" /* Sky coordinate axes */ -#include "skyframe.h" /* Celestial coordinate frames */ -#include "channel.h" /* I/O channels */ -#include "frame.h" /* Interface definition for this class */ -#include "frameset.h" /* Collections of Frames */ -#include "cmpframe.h" /* Compound Frames */ -#include "pal.h" /* SLALIB library interface */ -#include "unit.h" /* Units identification and mapping */ -#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 <math.h> -#include <stddef.h> -#include <stdio.h> -#include <string.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 const char *(* parent_getattrib)( AstObject *, const char *, int * ); -static int (* parent_testattrib)( AstObject *, const char *, int * ); -static void (* parent_clearattrib)( AstObject *, const char *, int * ); -static void (* parent_setattrib)( AstObject *, const char *, int * ); -static void (* parent_cleanattribs)( AstObject *, int * ); -static int (* parent_getobjsize)( AstObject *, int * ); - -#if defined(THREAD_SAFE) -static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); -#endif - -/* Define a variable to hold a SkyFrame which will be used for formatting - and unformatting ObsLat and ObsLon values. */ -static AstSkyFrame *skyframe; - -/* 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; \ - globals->AstFormatID_Init = 0; \ - globals->AstFormatID_Istr = 0; \ - globals->Label_Buff[ 0 ] = 0; \ - globals->Symbol_Buff[ 0 ] = 0; \ - globals->Title_Buff[ 0 ] = 0; \ - globals->AstFmtDecimalYr_Buff[ 0 ] = 0; - -/* Create the function that initialises global data for this module. */ -astMAKE_INITGLOBALS(Frame) - -#define class_init astGLOBAL(Frame,Class_Init) -#define class_vtab astGLOBAL(Frame,Class_Vtab) -#define getattrib_buff astGLOBAL(Frame,GetAttrib_Buff) -#define astformatid_strings astGLOBAL(Frame,AstFormatID_Strings) -#define astformatid_istr astGLOBAL(Frame,AstFormatID_Istr) -#define astformatid_init astGLOBAL(Frame,AstFormatID_Init) -#define label_buff astGLOBAL(Frame,Label_Buff) -#define symbol_buff astGLOBAL(Frame,Symbol_Buff) -#define title_buff astGLOBAL(Frame,Title_Buff) -#define astfmtdecimalyr_buff astGLOBAL(Frame,AstFmtDecimalYr_Buff) - - - -/* If thread safety is not needed, declare and initialise globals at static - variables. */ -#else - -/* Buffer returned by GetAttrib. */ -static char getattrib_buff[ GETATTRIB_BUFF_LEN + 1 ]; - -/* Strings returned by astFormatID */ -static char *astformatid_strings[ ASTFORMATID_MAX_STRINGS ]; - -/* Offset of next string in "AstFormatID_Strings" */ -static int astformatid_istr; - -/* "AstFormatID_Strings" array initialised? */ -static int astformatid_init; - -/* Default Label string buffer */ -static char label_buff[ LABEL_BUFF_LEN + 1 ]; - -/* Default Symbol buffer */ -static char symbol_buff[ SYMBOL_BUFF_LEN + 1 ]; - -/* Default Title string buffer */ -static char title_buff[ TITLE_BUFF_LEN + 1 ]; - -/* Buffer for result string */ -static char astfmtdecimalyr_buff[ ASTFMTDECIMALYR_BUFF_LEN + 1 ]; - - -/* Define the class virtual function table and its initialisation flag - as static variables. */ -static AstFrameVtab class_vtab; /* Virtual function table */ -static int class_init = 0; /* Virtual function table initialised? */ - -#endif - - -/* Prototypes for Private Member Functions. */ -/* ======================================== */ -static AstAxis *GetAxis( AstFrame *, int, int * ); -static AstFrame *PickAxes( AstFrame *, int, const int[], AstMapping **, 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 void MatchAxes( AstFrame *, AstFrame *, int *, int * ); -static void MatchAxesX( AstFrame *, AstFrame *, int *, int * ); -static AstLineDef *LineDef( AstFrame *, const double[2], const double[2], int * ); -static AstPointSet *FrameGrid( AstFrame *, int, const double *, const double *, int * ); -static AstPointSet *ResolvePoints( AstFrame *, const double [], const double [], AstPointSet *, AstPointSet *, int * ); -static AstPointSet *Transform( AstMapping *, AstPointSet *, int, AstPointSet *, int * ); -static char *CleanDomain( 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 *GetAttrib( AstObject *, const char *, int * ); -static const char *GetDefaultLabel( int, int * ); -static const char *GetDefaultSymbol( AstFrame *, int, int * ); -static const char *GetDefaultTitle( AstFrame *, int * ); -static const char *GetDomain( AstFrame *, int * ); -static const char *GetFormat( AstFrame *, int, int * ); -static const char *GetInternalUnit( AstFrame *, int, int * ); -static const char *GetLabel( AstFrame *, int, int * ); -static const char *GetNormUnit( AstFrame *, int, int * ); -static const char *GetSymbol( AstFrame *, int, int * ); -static const char *GetTitle( AstFrame *, int * ); -static const char *GetUnit( AstFrame *, int, int * ); -static const int *GetPerm( AstFrame *, 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 AxIn( AstFrame *, int, double, double, double, int, int * ); -static int ConsistentMaxAxes( AstFrame *, int, int * ); -static int ConsistentMinAxes( AstFrame *, int, int * ); -static int DefaultMaxAxes( AstFrame *, int * ); -static int DefaultMinAxes( AstFrame *, int * ); -static int DoNotSimplify( AstMapping *, int * ); -static int Equal( AstObject *, AstObject *, int * ); -static int Fields( AstFrame *, int, const char *, const char *, int, char **, int *, double *, int * ); -static int GetDigits( AstFrame *, int * ); -static int GetDirection( AstFrame *, int, int * ); -static int GetIsLinear( AstMapping *, int * ); -static int GetIsSimple( AstMapping *, int * ); -static int LineContains( AstFrame *, AstLineDef *, int, double *, int * ); -static int LineCrossing( AstFrame *, AstLineDef *, AstLineDef *, double **, int * ); -static int GetObjSize( AstObject *, int * ); -static void AxNorm( AstFrame *, int, int, int, double *, int * ); -static void CleanAttribs( AstObject *, int * ); -static void LineOffset( AstFrame *, AstLineDef *, double, double, double[2], 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 GetBottom( AstFrame *, int, int * ); -static int TestBottom( AstFrame *, int, int * ); -static void ClearBottom( AstFrame *, int, int * ); -static void SetBottom( AstFrame *, int, 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 double GetEpoch( AstFrame *, int * ); -static int TestEpoch( AstFrame *, int * ); -static void ClearEpoch( AstFrame *, int * ); -static void SetEpoch( 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 double GetObsAlt( AstFrame *, int * ); -static int TestObsAlt( AstFrame *, int * ); -static void ClearObsAlt( AstFrame *, int * ); -static void SetObsAlt( AstFrame *, double, int * ); - -static double GetDtai( AstFrame *, int * ); -static int TestDtai( AstFrame *, int * ); -static void ClearDtai( AstFrame *, int * ); -static void SetDtai( AstFrame *, double, int * ); - -static double GetDut1( AstFrame *, int * ); -static int TestDut1( AstFrame *, int * ); -static void ClearDut1( AstFrame *, int * ); -static void SetDut1( AstFrame *, double, int * ); - -static int GetActiveUnit( AstFrame *, int * ); -static int TestActiveUnit( AstFrame *, int * ); -static void SetActiveUnit( AstFrame *, int, int * ); - -static AstFrameSet *GetFrameVariants( AstFrame *, int * ); -static void SetFrameVariants( AstFrame *, AstFrameSet *, int * ); - -static int GetFrameFlags( AstFrame *, int * ); -static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); -static int GetMatchEnd( AstFrame *, int * ); -static int GetMaxAxes( AstFrame *, int * ); -static int GetMinAxes( AstFrame *, int * ); -static int GetNaxes( AstFrame *, int * ); -static int GetNin( AstMapping *, int * ); -static int GetNout( AstMapping *, int * ); -static int GetPermute( AstFrame *, int * ); -static int GetPreserveAxes( AstFrame *, int * ); -static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); -static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); -static int TestAttrib( AstObject *, const char *, int * ); -static int TestDigits( AstFrame *, int * ); -static int TestDirection( AstFrame *, int, int * ); -static int TestDomain( AstFrame *, int * ); -static int TestFormat( AstFrame *, int, int * ); -static int TestLabel( AstFrame *, int, int * ); -static int TestMatchEnd( AstFrame *, int * ); -static int TestMaxAxes( AstFrame *, int * ); -static int TestMinAxes( AstFrame *, int * ); -static int TestPermute( AstFrame *, int * ); -static int TestPreserveAxes( AstFrame *, int * ); -static int TestSymbol( AstFrame *, int, int * ); -static int TestTitle( AstFrame *, int * ); -static int TestUnit( AstFrame *, int, int * ); -static int IsUnitFrame( AstFrame *, int * ); -static int Unformat( AstFrame *, int, const char *, double *, int * ); -static int ValidateAxis( AstFrame *, int, int, const char *, int * ); -static AstSystemType ValidateSystem( AstFrame *, AstSystemType, const char *, int * ); -static AstSystemType SystemCode( AstFrame *, const char *, int * ); -static const char *SystemString( AstFrame *, AstSystemType, int * ); -static void AddUnderscores( char *, int * ); -static void CheckPerm( AstFrame *, const int *, const char *, int * ); -static void ClearAttrib( AstObject *, const char *, int * ); -static void ClearDigits( AstFrame *, int * ); -static void ClearDirection( AstFrame *, int, int * ); -static void ClearDomain( AstFrame *, int * ); -static void ClearFormat( AstFrame *, int, int * ); -static void ClearLabel( AstFrame *, int, int * ); -static void ClearMatchEnd( AstFrame *, int * ); -static void ClearMaxAxes( AstFrame *, int * ); -static void ClearMinAxes( AstFrame *, int * ); -static void ClearPermute( AstFrame *, int * ); -static void ClearPreserveAxes( AstFrame *, int * ); -static void ClearSymbol( AstFrame *, int, int * ); -static void ClearTitle( AstFrame *, int * ); -static void ClearUnit( AstFrame *, int, int * ); -static void Copy( const AstObject *, AstObject *, int * ); -static void Delete( AstObject *, int * ); -static void Dump( AstObject *, AstChannel *, int * ); -static void Intersect( AstFrame *, const double[2], const double[2], const double[2], const double[2], double[2], 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 PrimaryFrame( AstFrame *, int, AstFrame **, int *, int * ); -static void ReportPoints( AstMapping *, int, AstPointSet *, AstPointSet *, int * ); -static void Resolve( AstFrame *, const double [], const double [], const double [], double [], double *, double *, int * ); -static void SetAttrib( AstObject *, const char *, int * ); -static void SetAxis( AstFrame *, int, AstAxis *, int * ); -static void SetDigits( AstFrame *, int, int * ); -static void SetDirection( AstFrame *, int, int, int * ); -static void SetDomain( AstFrame *, const char *, int * ); -static void SetFormat( AstFrame *, int, const char *, int * ); -static void SetFrameFlags( AstFrame *, int, int * ); -static void SetLabel( AstFrame *, int, const char *, int * ); -static void SetMatchEnd( AstFrame *, int, int * ); -static void SetMaxAxes( AstFrame *, int, int * ); -static void SetMinAxes( AstFrame *, int, int * ); -static void SetPermute( AstFrame *, int, int * ); -static void SetPreserveAxes( AstFrame *, int, int * ); -static void SetSymbol( AstFrame *, int, const char *, int * ); -static void SetTitle( AstFrame *, const char *, int * ); -static void SetUnit( AstFrame *, int, const char *, int * ); -static void NewUnit( AstAxis *, const char *, const char *, const char *, const char *, int * ); -static void ValidateAxisSelection( AstFrame *, int, const int *, const char *, int * ); - -#if defined(THREAD_SAFE) -static int ManageLock( AstObject *, int, int, AstObject **, int * ); -#endif - -/* Member functions. */ -/* ================= */ -static const char *Abbrev( AstFrame *this, int axis, const char *fmt, - const char *str1, const char *str2, int *status ) { -/* -*+ -* Name: -* astAbbrev - -* Purpose: -* Abbreviate a formatted Frame axis value by skipping leading fields. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* const char *astAbbrev( AstFrame *this, int axis, const char *fmt, -* const char *str1, const char *str2 ) - -* Class Membership: -* Frame method. - -* Description: -* This function compares two Frame 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 Frame. -* axis -* The number of the Frame 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. If this is null, the returned pointer -* points to the start of the final field in str2. -* str2 -* Pointer to a constant null-terminated string containing the -* second formatted value. - -* 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 Frame 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: */ - AstAxis *ax; /* Pointer to Axis object */ - const char *result; /* Result pointer to return */ - -/* Initialise. */ - result = str2; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Validate the axis index and obtain a pointer to the required - Axis. */ - (void) astValidateAxis( this, axis, 1, "astAbbrev" ); - ax = astGetAxis( this, axis ); - -/* Invoke the Axis astAxisAbbrev method to perform the processing. */ - result = astAxisAbbrev( ax, fmt, str1, str2 ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* If an error occurred, clear the returned value. */ - if ( !astOK ) result = str2; - -/* Return the result. */ - return result; -} - -static void AddUnderscores( char *string, int *status ) { -/* -* Name: -* AddUnderscores - -* Purpose: -* Add underscores to a string in place of white space. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* void AddUnderscores( char *string, int *status ) - -* Class Membership: -* Frame member function. - -* Description: -* This function changes all white space characters in a string into -* the underscore character '_'. - -* Parameters: -* this -* Pointer to the Frame. -* string -* Pointer to the null terminated string to be processed. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables. */ - int i; /* Loop counter for characters */ - -/* Inspect each character in the string. */ - for ( i = 0; string[ i ]; i++ ) { - -/* If it is a white space character, replace it with an underscore. */ - if ( isspace( string[ i ] ) ) string[ i ] = '_'; - } -} - -static double Angle( AstFrame *this, const double a[], - const double b[], const double c[], int *status ) { -/* -*++ -* Name: -c astAngle -f AST_ANGLE - -* Purpose: -* Calculate the angle subtended by two points at a third point. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c double astAngle( AstFrame *this, const double a[], const double b[], -c const double c[] ) -f RESULT = AST_ANGLE( THIS, A, B, C, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function -f This routine -* 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: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c a -f A( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the first point. -c b -f B( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the second point. -c c -f C( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the third point. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astAngle -f AST_ANGLE = DOUBLE PRECISION -* 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 -c invoked with the AST error status set, or if it should fail for -f invoked with STATUS set to an error value, or if it should fail for -* any reason. -*-- -*/ - -/* Local Variables: */ - double *ab; /* Pointer to vector AB */ - double *cb; /* Pointer to vector CB */ - double cos; /* cosine of required angle */ - double anga; /* Angle from +ve Y to the line BA */ - double angc; /* Angle from +ve Y to the line BC */ - double result; /* Result value to return */ - double sla; /* Squared length of vector AB */ - double slc; /* Squared length of vector CB */ - double sp; /* Scalar product of AB and CB */ - int axis; /* Axis index */ - int naxes; /* Number of Frame axes */ - int ok; /* Supplied points OK? */ - -/* Initialise. */ - result = AST__BAD; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Assume everything is ok */ - ok = 1; - -/* Obtain the number of Frame axes. */ - naxes = astGetNaxes( this ); - -/* Obtain workspace. */ - ab = (double *) astMalloc( sizeof(double)*naxes ); - cb = (double *) astMalloc( sizeof(double)*naxes ); - -/* Check all positions are good, and form the vectors from b to a, and - from b to c. Also find the squared length of each vector. */ - if( astOK ) { - sla = 0.0; - slc = 0.0; - for( axis = 0; axis < naxes; axis++ ) { - if( a[ axis ] == AST__BAD || b[ axis ] == AST__BAD || - c[ axis ] == AST__BAD ) { - ok = 0; - break; - } else { - ab[ axis ] = a[ axis ] - b[ axis ]; - cb[ axis ] = c[ axis ] - b[ axis ]; - sla += ( ab[ axis ] )*( ab[ axis ] ); - slc += ( cb[ axis ] )*( cb[ axis ] ); - } - } - -/* Check that neither of the vectors have zero length. */ - if( sla == 0 || slc == 0 ) ok = 0; - -/* Only proceed if these checks were passed. */ - if ( ok ) { - -/* Deal first with 2-dimensional Frames. */ - if( naxes == 2 ) { - -/* Find the angle from +ve Y to the line BA. */ - anga = atan2( ab[ 0 ], ab[ 1 ] ); - -/* Find the angle from +ve Y to the line BC. */ - angc = atan2( cb[ 0 ], cb[ 1 ] ); - -/* Find the difference, folded into the range +/- PI. */ - result = palDrange( angc - anga ); - -/* Now deal with Frames with more than 2 axes. */ - } else { - -/* Form the scalar product of the two vectors. */ - sp = 0.0; - for( axis = 0; axis < naxes; axis++ ) { - sp += ab[ axis ]*cb[ axis ]; - } - -/* Derive the required angle from the normalized scalar product. */ - cos = sp/sqrt( sla*slc ); - if( cos > 1.0 ) { - cos = 1.0; - } else if( cos < -1.0 ) { - cos = -1.0; - } - result =acos( cos ); - } - } - } - -/* Free the work space. */ - ab = (double *) astFree( (void *) ab ); - cb = (double *) astFree( (void *) cb ); - -/* Return the result. */ - return result; -} - -static double AxAngle( AstFrame *this, const double a[], const double b[], int axis, int *status ) { -/* -*++ -* Name: -c astAxAngle -f AST_AXANGLE - -* Purpose: -* Returns the angle from an axis, to a line through two points. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c double astAxAngle( AstFrame *this, const double a[], const double b[], int axis ) -f RESULT = AST_AXANGLE( THIS, A, B, AXIS, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function -f This routine -* 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: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c a -f A( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the first point. -c b -f B( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the second point. -c axis -f AXIS = INTEGER (Given) -* The number of the Frame axis from which the angle is to be -* measured (axis numbering starts at 1 for the first axis). -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astAxAngle -f AST_AXANGLE = DOUBLE PRECISION -* 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 [-PI/2,+PI/2], 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: -c - The geodesic curve used by this function is the path of -f - The geodesic curve used by this routine is the path of -* shortest distance between two points, as defined by the -c astDistance function. -f AST_DISTANCE 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: */ - double *aa; /* Pointer to third point */ - double ab; /* Absolute value of component */ - double mxab; /* Largest absolute value of component */ - double result; /* The returned value */ - int iaxis; /* Axis index */ - int naxes; /* Number of Frame axes */ - int ok; /* Are values ok to use? */ - -/* Initialise. */ - result = AST__BAD; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis - 1, 1, "astAxAngle" ); - -/* Obtain the number of Frame axes. */ - naxes = astGetNaxes( this ); - -/* Obtain workspace. */ - aa = (double *) astMalloc( sizeof(double)*naxes ); - -/* Create a position which is offset slightly from point A in the - positive direction of the specified axis. Also get the largest absolute - value of any component of the vector AB. */ - if( astOK ) { - ok = 1; - mxab = 0.0; - - for( iaxis = 0; iaxis < naxes; iaxis++ ) { - if( a[ iaxis ] != AST__BAD && b[ iaxis ] != AST__BAD ) { - aa[ iaxis ] = a[ iaxis ]; - ab = fabs( a[ iaxis ] - b[ iaxis ] ); - if( ab > mxab ) mxab = ab; - } else { - ok = 0; - break; - } - } - - if( ok ) { - - if( a[ axis - 1 ] != 0.0 ) { - aa[ axis - 1 ] += 10000.0*DBL_EPSILON*fabs( a[ axis - 1 ] ); - - } else if( b[ axis - 1 ] != 0.0 ) { - aa[ axis - 1 ] = 10000.0*DBL_EPSILON*fabs( b[ iaxis - 1 ] ); - - } else if( mxab != 0.0 ) { - aa[ axis - 1 ] = 10000.0*DBL_EPSILON*mxab; - - } else { - aa[ axis - 1 ] = 1.0; - } - -/* Use astAngle to get the required angle. */ - result = astAngle( this, aa, a, b ); - } - } - -/* Free the workspace. */ - aa = (double *) astFree( (void *) aa ); - -/* Return the result. */ - return result; - -} - -static double AxDistance( AstFrame *this, int axis, double v1, double v2, int *status ) { -/* -*++ -* Name: -c astAxDistance -f AST_AXDISTANCE - -* Purpose: -* Find the distance between two axis values. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c double astAxDistance( AstFrame *this, int axis, double v1, double v2 ) -f RESULT = AST_AXDISTANCE( THIS, AXIS, V1, V2, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function returns a signed value representing the axis increment -f This routine 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: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c axis -f AXIS = INTEGER (Given) -* The index of the axis to which the supplied values refer. The -* first axis has index 1. -c v1 -f V1 = DOUBLE PRECISION (Given) -* The first axis value. -c v2 -f V2 = DOUBLE PRECISION (Given) -* The second axis value. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astAxDistance -f AST_AXDISTANCE = DOUBLE PRECISION -* The distance from the first to the second axis value. - -* Notes: -* - This function will return a "bad" result value (AST__BAD) if -* any of the input values has this value. -* - A "bad" value will also be returned if this function is -c invoked with the AST error status set, or if it should fail for -f invoked with STATUS set to an error value, or if it should fail for -* any reason. -*-- - -* Implementation Deficiencies; -* - The protected interface for this function uses 1-based axis -* numbering (like the public interface), rather than the more usual -* zero-based system used by all other protected interfaces. There is -* no real reason for this, and it should be changed at some time. - -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - double result; /* The returned answer */ - -/* Initialise. */ - result = AST__BAD; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Validate the axis index and obtain a pointer to the required Axis. */ - (void) astValidateAxis( this, axis - 1, 1, "astAxDistance" ); - ax = astGetAxis( this, axis - 1 ); - -/* Use the AxisDistance method associated with the Axis. */ - if( astOK ) result = astAxisDistance( ax, v1, v2 ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* Return the result. */ - return result; - -} - -static void AxNorm( AstFrame *this, int axis, int oper, int nval, - double *values, int *status ){ -/* -*++ -* Name: -c astAxNorm -f AST_AXNORM - -* Purpose: -* Normalise an array of axis values. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c void astAxNorm( AstFrame *this, int axis, int oper, int nval, -c double *values, int *status ) -f CALL AST_AXNORM( THIS, AXIS, OPER, NVAL, VALUES, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function -f This routine -* modifies a supplied array of axis values so that they are normalised -* in the manner indicated by -c parameter "oper". -f argument 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]. See the -* "Applicability:" section below for details. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c axis -f AXIS = INTEGER (Given) -* The index of the axis to which the supplied values refer. The -* first axis has index 1. -c oper -f OPER = INTEGER (Given) -* Indicates the type of normalisation to be applied. If zero is -* supplied, the normalisation will be the same as that performed by -c function astNorm. -f routine AST_NORM. -* If 1 is supplied, the normalisation will be chosen automatically -* so that the resulting list has the smallest range. -c nval -f NVAL = INTEGER (Given) -* The number of points in the values array. -c values -f VALUES( NVAL ) = DOUBLE PRECISION (Given and Returned) -* On entry, the axis values to be normalised. Modified on exit to -* hold the normalised values. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Applicability: -* SkyFrame -c If "oper" -f If OPER -* is 0, longitude values are returned in the range [0,2*PI]. -c If "oper" -f If OPER -* is 1, longitude values are returned in either the range -* [0,2*PI] or [-PI,PI]. The choice is made so that that the -* resulting list has the smallest range. Latitude values are -* always returned in the range [-PI,PI]. -* All other classes of Frame -* The supplied axis values are returned unchanged. - -*-- - -* Implementation Deficiencies; -* - The protected interface for this function uses 1-based axis -* numbering (like the public interface), rather than the more usual -* zero-based system used by all other protected interfaces. There is -* no real reason for this, and it should be changed at some time. - -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Validate the axis index and obtain a pointer to the required Axis. */ - (void) astValidateAxis( this, axis - 1, 1, "astAxNorm" ); - ax = astGetAxis( this, axis - 1 ); - -/* Validate ther "oper" value. */ - if( ( oper < 0 || oper > 1 ) && astOK ) { - astError( AST__OPRIN, "astAxNorm(%s): Invalid operation %d.", status, - astGetClass( this ), oper ); - } - -/* Use the AxisNormValues method associated with the Axis. */ - if( astOK ) astAxisNormValues( ax, oper, nval, values ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); -} - -static int AxIn( AstFrame *this, int axis, double lo, double hi, double val, - int closed, int *status ){ -/* -*+ -* Name: -* astAxIn - -* Purpose: -* Test if an axis value lies within a given interval. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astAxIn( AstFrame *this, int axis, double lo, double hi, double val, -* int closed ) - -* Class Membership: -* Frame member function. - -* Description: -* This function returns non-zero if a given axis values lies within a -* given axis interval. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The index of the axis. The first axis has index 0. -* lo -* The lower axis limit of the interval. -* hi -* The upper axis limit of the interval. -* val -* The axis value to be tested. -* closed -* If non-zero, then the lo and hi axis values are themselves -* considered to be within the interval. Otherwise they are outside. - -* Returned Value: -* Non-zero if the test value is inside the interval. - -* Applicability: -* Frame -* Uses simple Euclidean test -* SkyFrame -* All angles which are numerically between "lo" and "hi" are within -* the interval. Angle outside this range are also within the interval -* if they can be brought into the range by addition or subtraction -* of a multiple of 2.PI. -*- -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - int result; /* Returned value */ - -/* For speed, omit the astOK check and axis validation (since this is - protected code, AST should get it right). Obtain a pointer to the - required Axis. */ - ax = astGetAxis( this, axis ); - -/* Use the AxisIn method associated with the Axis. */ - result = ax ? astAxisIn( ax, lo, hi, val, closed ) : 0; - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* Return the result. */ - return result; -} - -static double AxOffset( AstFrame *this, int axis, double v1, double dist, int *status ) { -/* -*++ -* Name: -c astAxOffset -f AST_AXOFFSET - -* Purpose: -* Add an increment onto a supplied axis value. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c double astAxOffset( AstFrame *this, int axis, double v1, double dist ) -f RESULT = AST_AXOFFSET( THIS, AXIS, V1, DIST, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function returns an axis value formed by adding a signed axis -f This routine 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: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c axis -f AXIS = INTEGER (Given) -* The index of the axis to which the supplied values refer. The -* first axis has index 1. -c v1 -f V1 = DOUBLE PRECISION (Given) -* The original axis value. -c dist -f DIST = DOUBLE PRECISION (Given) -* The axis increment to add to the original axis value. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astAxOffset -f AST_AXOFFSET = DOUBLE PRECISION -* The incremented axis value. - -* Notes: -* - This function will return a "bad" result value (AST__BAD) if -* any of the input values has this value. -* - A "bad" value will also be returned if this function is -c invoked with the AST error status set, or if it should fail for -f invoked with STATUS set to an error value, or if it should fail for -* any reason. -*-- -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - double result; /* The returned answer */ - -/* Initialise. */ - result = AST__BAD; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Validate the axis index and obtain a pointer to the required Axis. */ - (void) astValidateAxis( this, axis - 1, 1, "astAxOffset" ); - ax = astGetAxis( this, axis - 1 ); - -/* Use the AxisOffset method associated with the Axis. */ - if( astOK ) result = astAxisOffset( ax, v1, dist ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* Return the result. */ - return result; - -} - -static double Centre( AstFrame *this, int axis, double value, double gap, int *status ) { -/* -*+ -* Name: -* astCentre - -* Purpose: -* Find a "nice" central value for tabulating Axis values. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* double astCentre( AstFrame *this, int axis, double value, double gap ) - -* Class Membership: -* Frame method. - -* 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 gap 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: */ - AstAxis *ax; /* Pointer to Axis object */ - double result; /* The nice central value */ - -/* Check the global error status. */ - if ( !astOK ) return 0.0; - -/* Validate the axis index and obtain a pointer to the required - Axis. */ - (void) astValidateAxis( this, axis, 1, "astCentre" ); - ax = astGetAxis( this, axis ); - -/* Find the nice central value. */ - result = astAxisCentre( ax, value, gap ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0.0; - -/* Return the result. */ - return result; -} - -static void CheckPerm( AstFrame *this, const int *perm, const char *method, int *status ) { -/* -*+ -* Name: -* astCheckPerm - -* Purpose: -* Check that an array contains a valid permutation. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astCheckPerm( AstFrame *this, const int *perm, const char *method ) - -* Class Membership: -* Frame method. - -* 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. - -* 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: */ - int *there; /* Pointer to temporary array */ - int axis; /* Loop counter for axes */ - int naxes; /* Number of Frame axes */ - int valid; /* Permutation array is valid? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Initialise. */ - valid = 1; - -/* Obtain the number of Frame axes and allocate a temporary array of integers - with the same number of elements. */ - naxes = astGetNaxes( this ); - there = astMalloc( sizeof( int ) * (size_t) naxes ); - if ( astOK ) { - -/* Initialise the temporary array to zero. */ - for ( axis = 0; axis < naxes; axis++ ) there[ axis ] = 0; - -/* Scan the permutation array, checking that each permuted axis index it - contains is within the correct range. Note an error and quit checking - if an invalid value is found. */ - for ( axis = 0; axis < naxes; axis++ ) { - if ( ( perm[ axis ] < 0 ) || ( perm[ axis ] >= naxes ) ) { - valid = 0; - break; - -/* Use the temporary array to count how many times each valid axis index - occurs. */ - } else { - there[ perm[ axis ] ]++; - } - } - -/* If all the axis indices were within range, check to ensure that each value - occurred only once. */ - if ( valid ) { - for ( axis = 0; axis < naxes; axis++ ) { - -/* Note an error and quit checking if any value did not occur exactly once. */ - if ( there[ axis ] != 1 ) { - valid = 0; - break; - } - } - } - } - -/* Free the temporary array. */ - there = astFree( there ); - -/* If an invalid permutation was detected and no other error has - occurred, then report an error (note we convert to one-based axis - numbering in the error message). */ - if ( !valid && astOK ) { - astError( AST__PRMIN, "%s(%s): Invalid axis permutation array.", status, - method, astGetClass( this ) ); - astError( AST__PRMIN, "Each axis index should lie in the range 1 to %d " - "and should occur only once.", status, naxes ); - } -} - -static void CleanAttribs( AstObject *this_object, int *status ) { -/* -* Name: -* CleanAttribs - -* Purpose: -* Clear any invalid set attribute values. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* void CleanAttribs( AstObject *this_object, int *status ) - -* Class Membership: -* Frame member function (over-rides the protected astCleanAttribs -* method inherited from the Object class). - -* Description: -* This function clears any attributes that are currently set to -* invalid values in thr supplied object. - -* Parameters: -* this -* Pointer to the Object to be cleaned. - -*/ - -/* Local Variables; */ - AstAxis *ax; - AstFrame *this; - int i; - int nax; - int reporting; - -/* Check inherited status */ - if( !astOK ) return; - -/* Get a pointer to the Frame structure. */ - this = (AstFrame *) this_object; - -/* Defer error reporting, as required by the astCLEAN_ATTRIB macro. */ - reporting = astReporting( 0 ); - -/* Clean attributes in any Objects contained within "this". */ - nax = astGetNaxes( this ); - for( i = 0; i < nax; i++ ) { - ax = astGetAxis( this, i ); - astCleanAttribs( ax ); - ax = astAnnul( ax ); - } - -/* Clean attributes of this class. */ - astCLEAN_ATTRIB(System) - astCLEAN_ATTRIB(AlignSystem) - -/* Re-establish error reporting. */ - astReporting( reporting ); - -/* Invoke the method inherited form the parent to clean attributes - defined by the parent class. */ - (*parent_cleanattribs)( this_object, status ); -} - -static char *CleanDomain( char *domain, int *status ) { -/* -* Name: -* CleanDomain - -* Purpose: -* Clean a Domain string and convert to upper case. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* char *CleanDomain( char *domain, int *status ) - -* Class Membership: -* Frame member function. - -* Description: -* This function removes all white space from a string and converts -* other characters to upper case. It is intended for cleaning up -* values supplied for the Domain attribute of a Frame. - -* Parameters: -* domain -* Pointer to the null terminated Domain string to be modified. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The pointer value "domain" is always returned (even under error -* conditions). -*/ - -/* Local Variables: */ - int i; /* Loop counter for characters */ - int j; /* Good character count */ - -/* Check the global error status. */ - if ( !astOK ) return domain; - -/* Eliminate white space characters and convert the rest to upper - case. */ - for ( i = j = 0; domain[ i ]; i++ ) { - if ( !isspace( domain[ i ] ) ) domain[ j++ ] = toupper( domain[ i ] ); - } - domain[ j ] = '\0'; - -/* Return the string pointer. */ - return domain; -} - -static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { -/* -* Name: -* ClearAttrib - -* Purpose: -* Clear an attribute value for a Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* void ClearAttrib( AstObject *this, const char *attrib, int *status ) - -* Class Membership: -* Frame member function (over-rides the astClearAttrib protected -* method inherited from the Mapping class). - -* Description: -* This function clears the value of a specified attribute for a -* Frame, so that the default value will subsequently be used. - -* Parameters: -* this -* Pointer to the Frame. -* 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. - -* Notes: -* - This function uses one-based axis numbering so that it is -* suitable for external (public) use. -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis */ - AstFrame *pfrm; /* Pointer to primary Frame containing axis */ - AstFrame *this; /* Pointer to the Frame structure */ - char pfrm_attrib[ 100 ]; /* Primary Frame attribute */ - char *axis_attrib; /* Pointer to axis attribute name */ - const char *old_attrib; /* Pointer to supplied attribute name string */ - int axis; /* Frame axis number */ - int axis_nc; /* No. characters in axis attribute name */ - int free_axis_attrib; /* Should axis_attrib be freed? */ - int has_axis; /* Does attrib name include axis specifier? */ - int len; /* Length of attrib string */ - int nc; /* No. characters read by astSscanf */ - int oldrep; /* Original error reporting state */ - int paxis; /* Axis index within primary frame */ - int used; /* Could the setting string be used? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_object; - -/* Set a flag indicating if the attribute name includes an axis - specifier. */ - has_axis = ( strchr( attrib, '(' ) != NULL ); - -/* A flag indicating that we do not need to free the axis_attrib memory. */ - free_axis_attrib = 0; - -/* Initialise things to avoid compiler warnings. */ - axis_attrib = NULL; - old_attrib = NULL; - -/* Jump back to here if we are trying the same attribute but with an explicit - axis "(1)" added to the end of the name. */ -L1: - -/* Obtain the length of the "attrib" string. */ - len = strlen( attrib ); - -/* Check the attribute name and clear the appropriate attribute. */ - -/* Digits. */ -/* ------- */ - if ( !strcmp( attrib, "digits" ) ) { - astClearDigits( this ); - -/* Digits(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "digits(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - -/* There is no function to clear the Digits attribute for an axis - directly, so obtain a pointer to the Axis and use this to clear the - attribute. */ - (void) astValidateAxis( this, axis - 1, 1, "astClearDigits(axis)" ); - ax = astGetAxis( this, axis - 1 ); - astClearAxisDigits( ax ); - ax = astAnnul( ax ); - -/* Direction(axis). */ -/* ---------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "direction(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - astClearDirection( this, axis - 1 ); - -/* Epoch. */ -/* ------ */ - } else if ( !strcmp( attrib, "epoch" ) ) { - astClearEpoch( this ); - -/* Top(axis). */ -/* ---------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "top(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - astClearTop( this, axis - 1 ); - -/* Bottom(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "bottom(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - astClearBottom( this, axis - 1 ); - -/* Domain. */ -/* ------- */ - } else if ( !strcmp( attrib, "domain" ) ) { - astClearDomain( this ); - -/* Format(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "format(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - astClearFormat( this, axis - 1 ); - -/* Label(axis). */ -/* ------------ */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "label(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - astClearLabel( this, axis - 1 ); - -/* MatchEnd. */ -/* --------- */ - } else if ( !strcmp( attrib, "matchend" ) ) { - astClearMatchEnd( this ); - -/* MaxAxes. */ -/* -------- */ - } else if ( !strcmp( attrib, "maxaxes" ) ) { - astClearMaxAxes( this ); - -/* MinAxes. */ -/* -------- */ - } else if ( !strcmp( attrib, "minaxes" ) ) { - astClearMinAxes( this ); - -/* Permute. */ -/* -------- */ - } else if ( !strcmp( attrib, "permute" ) ) { - astClearPermute( this ); - -/* PreserveAxes. */ -/* ------------- */ - } else if ( !strcmp( attrib, "preserveaxes" ) ) { - astClearPreserveAxes( this ); - -/* Symbol(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "symbol(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - astClearSymbol( this, axis - 1 ); - -/* System. */ -/* ------- */ - } else if ( !strcmp( attrib, "system" ) ) { - astClearSystem( this ); - -/* AlignSystem. */ -/* ------------ */ - } else if ( !strcmp( attrib, "alignsystem" ) ) { - astClearAlignSystem( this ); - -/* Title. */ -/* ------ */ - } else if ( !strcmp( attrib, "title" ) ) { - astClearTitle( this ); - -/* Unit(axis). */ -/* ----------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "unit(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - astClearUnit( this, axis - 1 ); - -/* ObsLat. */ -/* ------- */ - } else if ( !strcmp( attrib, "obslat" ) ) { - astClearObsLat( this ); - -/* ObsLon. */ -/* ------- */ - } else if ( !strcmp( attrib, "obslon" ) ) { - astClearObsLon( this ); - -/* ObsAlt. */ -/* ------- */ - } else if ( !strcmp( attrib, "obsalt" ) ) { - astClearObsAlt( this ); - -/* Dtai */ -/* --- */ - } else if ( !strcmp( attrib, "dtai" ) ) { - astClearDtai( this ); - -/* Dut1 */ -/* --- */ - } else if ( !strcmp( attrib, "dut1" ) ) { - astClearDut1( this ); - -/* Read-only attributes. */ -/* --------------------- */ -/* Test if the attribute name matches any of the read-only attributes - of this class. If it does, then report an error. */ - } else if ( !strcmp( attrib, "naxes" ) || - !strncmp( attrib, "normunit", 8 ) || - !strncmp( attrib, "internalunit", 12 ) ) { - 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); - -/* Other axis attributes. */ -/* ---------------------- */ -/* If the attribute was not identified above, but appears to refer to - a Frame axis, then it may refer to an Axis object of a derived type - (which has additional attributes not recognised here). */ - } else if( !free_axis_attrib && ( nc = 0, - ( 1 == astSscanf( attrib, "%*[^()]%n(%d)%n", - &axis_nc, &axis, &nc ) ) - && ( nc >= len ) ) ) { - -/* Validate the axis index and extract the attribute name. */ - (void) astValidateAxis( this, axis - 1, 1, "astClear" ); - axis_attrib = astString( attrib, axis_nc ); - -/* Obtain a pointer to the Axis object. */ - ax = astGetAxis( this, axis - 1 ); - if( astOK ) { - -/* Assume that we will be able to use the attribute name. */ - used = 1; - -/* Temporarily switch off error reporting so that if the following attempt - to access the axis attribute fails, we can try to interpret the - attribute name as an attribute of the primary Frame containing the - specified axis. Any errors reported in this context will simply be - ignored, in particularly they are not deferred for later delivery. */ - oldrep = astReporting( 0 ); - -/* Use the Axis astClearAttrib method to clear the attribute value. */ - astClearAttrib( ax, axis_attrib ); - -/* If the above call failed with a status of AST__BADAT, indicating that - the attribute name was not recognised, clear the status so that we can - try to interpret the attribute name as an attribute of the primary Frame - containing the specified axis. */ - if( astStatus == AST__BADAT ) { - astClearStatus; - -/* Find the primary Frame containing the specified axis. */ - astPrimaryFrame( this, axis - 1, &pfrm, &paxis ); - -/* Only attempt to use the primary Frame if it is not the same as "this" - - otherwise we could end up in an infinite loop. */ - if( pfrm != this ) { - -/* astPrimaryFrame returns the original - unpermuted - axis index within - the primary Frame. So we need to take into account any axis permutation - which has been applied to the primary Frame when forming the attribute name - to use below. Find the permuted (external) axis index which corresponds to - the internal (unpermuted) axis index "paxis". */ - paxis = astValidateAxis( pfrm, paxis, 0, "astClear" ); - -/* Modify the attribute name to refer to the axis numbering of the - primary frame. */ - sprintf( pfrm_attrib, "%s(%d)", axis_attrib, paxis + 1 ); - -/* Attempt to clear the attribute as an attribute of the primary Frame. */ - astClearAttrib( pfrm, pfrm_attrib ); - -/* If this failed, clear the status and indicate that we have not managed to - use the attribute name. */ - if( !astOK ) { - astClearStatus; - used = 0; - } - - } else { - used = 0; - } - -/* If not found attempt to clear the attribute value in the Axis, omitting - the axis index. */ - if( ! used ) { - astClearAttrib( pfrm, axis_attrib ); - if( !astOK ) { - astClearStatus; - } else { - used = 1; - } - } - -/* Annul the primary Frame pointer. */ - pfrm = astAnnul( pfrm ); - } - -/* Re-instate the original error reporting state. */ - astReporting( oldrep ); - -/* If we could not use the attribute name, attempt to clear the axis - attribute again, this time retaining the error report. This is done - to ensure the user gets an appropriate error message. */ - if( !used ) astClearAttrib( ax, axis_attrib ); - } - -/* Annul the Axis pointer and free the memory holding the attribute - name. */ - ax = astAnnul( ax ); - axis_attrib = astFree( axis_attrib ); - -/* Not recognised. */ -/* --------------- */ -/* If the attribute is still not recognised, and the Frame has only 1 axis, - and the attribute name does not already include an axis specifier, try - again after appending "(1)" to the end of the attribute name. */ - } else if( !has_axis && astGetNaxes( this ) == 1 ) { - -/* Take a copy of the supplied name, allowing 3 extra characters for the - axis specifier "(1)". */ - axis_attrib = astMalloc( len + 4 ); - if( axis_attrib ) memcpy( axis_attrib, attrib, len ); - -/* Indicate we should free the axis_attrib memory. */ - free_axis_attrib = 1; - -/* Add in the axis specifier. */ - strcpy( axis_attrib + len, "(1)" ); - -/* Use the new attribute name instead of the supplied name. */ - old_attrib = attrib; - attrib = axis_attrib; - -/* Indicate the attribute name now has an axis specifier. */ - has_axis = 1; - -/* Jump back to try interpreting the new attribute name. */ - goto L1; - -/* Not recognised. */ -/* --------------- */ -/* If the attribute name is still not recognised, pass it on to the parent - method for further interpretation. First re-instate the original attrib - name string if it was changed above. */ - } else { - if( free_axis_attrib ) { - attrib = old_attrib; - axis_attrib = astFree( axis_attrib ); - } - (*parent_clearattrib)( this_object, attrib, status ); - } -} - -static void ClearUnit( AstFrame *this, int axis, int *status ) { -/* -* Name: -* ClearUnit - -* Purpose: -* Clear the Unit attribute of a Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void ClearUnit( AstFrame *this, int axis, int *status ) - -* Class Membership: -* Frame method. - -* Description: -* This function clears the Unit value for an axis of a Frame. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The number of the axis (zero-based) for which the Unit value is to -* be cleared. -* unit -* The new value to be set. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* void. -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - const char *units; /* Pointer to units string */ - char *old_units; /* Pointer to copy of original units */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis, 1, "astSetUnit" ); - -/* Do nothing more if the attribute is already cleared. */ - if( astTestUnit( this, axis ) ) { - -/* Obtain a pointer to the required Axis. */ - ax = astGetAxis( this, axis ); - -/* Save a copy of the old units. */ - units = astGetAxisUnit( ax ); - old_units = astStore( NULL, units, strlen( units ) + 1 ); - -/* Clear the Axis Unit attribute value, and then get a pointer to the - new default Units string. */ - astClearAxisUnit( ax ); - units = astGetUnit( this, axis ); - -/* The new unit may require the Label and/or Symbol to be changed, but - only if the Frames ActiveUnit flag is set. */ - if( astGetActiveUnit( this ) ) NewUnit( ax, old_units, units, - "astSetUnit", astGetClass( this ), status ); - -/* Free resources. */ - old_units = astFree( old_units ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - } -} - -static int ConsistentMaxAxes( AstFrame *this, int value, int *status ) { -/* -* Name: -* ConsistentMaxAxes - -* Purpose: -* Ensure a consistent value when setting the MaxAxes attribute. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int ConsistentMaxAxes( AstFrame *this, int value, int *status ) - -* Class Membership: -* Frame member function. - -* Description: -* This function accepts a value which is to be set for a Frame's MaxAxes -* attribute and returns an appropriately adjusted value to be assigned -* to the Frame structure's max_axes component. If necessary, the Frame's -* MinAxes attribute is adjusted to remain consistent with the new MaxAxes -* value (but note that the MaxAxes value itself is not assigned by this -* function). - -* Parameters: -* this -* Pointer to the Frame. -* value -* The new value being set for the MaxAxes attribute. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The value to be assigned to the max_axes component. - -* Notes: -* - A value of -INT_MAX will be returned if this function is -* invoked with the global error status set, or if it should fail -* for any reason. -*/ - -/* Local Variables: */ - int result; /* Result to be returned */ - -/* Check the global error status. */ - if ( !astOK ) return -INT_MAX; - -/* Ensure that the result value isn't negative. */ - result = ( value >= 0 ) ? value : 0; - -/* Check if the MinAxes attribute is set. If not, its default value will be - consistent with the MaxAxes value (the DefaultMinAxes function ensures - this). Otherwise, obtain its value to check for consistency. */ - if ( astTestMinAxes( this ) ) { - -/* If necessary, set a new MinAxes value to prevent it exceeding the MaxAxes - value about to be returned. */ - if ( astGetMinAxes( this ) > result ) astSetMinAxes( this, result ); - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = -INT_MAX; - -/* Return the result. */ - return result; -} - -static int ConsistentMinAxes( AstFrame *this, int value, int *status ) { -/* -* Name: -* ConsistentMinAxes - -* Purpose: -* Ensure a consistent value when setting the MinAxes attribute. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int ConsistentMinAxes( AstFrame *this, int value, int *status ) - -* Class Membership: -* Frame member function. - -* Description: -* This function accepts a value which is to be set for a Frame's MinAxes -* attribute and returns an appropriately adjusted value to be assigned -* to the Frame structure's min_axes component. If necessary, the Frame's -* MaxAxes attribute is adjusted to remain consistent with the new MinAxes -* value (but note that the MinAxes value itself is not assigned by this -* function). - -* Parameters: -* this -* Pointer to the Frame. -* value -* The new value being set for the MinAxes attribute. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The value to be assigned to the min_axes component. - -* Notes: -* - A value of -INT_MAX will be returned if this function is -* invoked with the global error status set, or if it should fail -* for any reason. -*/ - -/* Local Variables: */ - int result; /* Result to be returned */ - -/* Check the global error status. */ - if ( !astOK ) return -INT_MAX; - -/* Ensure that the result value isn't negative. */ - result = ( value >= 0 ) ? value : 0; - -/* Check if the MaxAxes attribute is set. If not, its default value will be - consistent with the MinAxes value (the DefaultMaxAxes function ensures - this). Otherwise, obtain its value to check for consistency. */ - if ( astTestMaxAxes( this ) ) { - -/* If necessary, set a new MaxAxes value to prevent it being less than the - MinAxes value about to be returned. */ - if ( astGetMaxAxes( this ) < result ) astSetMaxAxes( this, result ); - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = -INT_MAX; - -/* Return the result. */ - return result; -} - -static AstFrameSet *Convert( AstFrame *from, AstFrame *to, - const char *domainlist, int *status ) { -/* -*++ -* Name: -c astConvert -f AST_CONVERT - -* Purpose: -* Determine how to convert between two coordinate systems. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c AstFrameSet *astConvert( AstFrame *from, AstFrame *to, -c const char *domainlist ) -f RESULT = AST_CONVERT( FROM, TO, DOMAINLIST, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -* This function compares two Frames and determines whether it is -* possible to convert between the coordinate systems which they -* 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. -* -* The same function may also be used to determine how to convert -* between two FrameSets (or between a Frame and a FrameSet, or -* vice versa). This mode is intended for use when (for example) -* two images have been calibrated by attaching a FrameSet to each. -c astConvert might then be used to search for a -f AST_CONVERT might then be used to search for a -* celestial coordinate system that both images have in common, and -* the result could then be used to convert between the pixel -* coordinates of both images -- having effectively used their -* celestial coordinate systems to align them. -* -* When using FrameSets, there may be more than one possible -* intermediate coordinate system in which to perform the -* conversion (for instance, two FrameSets might both have -* celestial coordinates, detector coordinates, pixel coordinates, -* etc.). A comma-separated list of coordinate system domains may -* therefore be given which defines a priority order to use when -* selecting the intermediate coordinate system. The path used for -* conversion must go via an intermediate coordinate system whose -* Domain attribute matches one of the domains given. If conversion -* cannot be achieved using the first domain, the next one is -* considered, and so on, until success is achieved. - -* Parameters: -c from -f FROM = INTEGER (Given) -* Pointer to a Frame which represents the "source" coordinate -* system. This is the coordinate system in which you already -* have coordinates available. -* -* If a FrameSet is given, its current Frame (as determined by -* its Current attribute) is taken to describe the source -* coordinate system. Note that the Base attribute of this -* FrameSet may be modified by this function to indicate which -* intermediate coordinate system was used (see under -* "FrameSets" in the "Applicability" section for details). -c to -f TO = INTEGER (Given) -* Pointer to a Frame which represents the "destination" -* coordinate system. This is the coordinate system into which -* you wish to convert your coordinates. -* -* If a FrameSet is given, its current Frame (as determined by -* its Current attribute) is taken to describe the destination -* coordinate system. Note that the Base attribute of this -* FrameSet may be modified by this function to indicate which -* intermediate coordinate system was used (see under -* "FrameSets" in the "Applicability" section for details). -c domainlist -f DOMAINLIST = CHARACTER * ( * ) (Given) -c Pointer to a null-terminated character string containing a -f A 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 an intermediate coordinate system 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 coordinate systems -* should be considered, regardless of their domains. -* -* This list is case-insensitive and all white space is ignored. -* If you do not wish to restrict the domain in this way, -c you should supply an empty string. This is normally -f you should supply a blank string. This is normally -* appropriate if either of the source or destination coordinate -* systems are described by Frames (rather than FrameSets), -* since there is then usually only one possible choice of -* intermediate coordinate system. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astConvert() -f AST_CONVERT = INTEGER -* 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 -c system, corresponding to the "from" parameter. Frame number 2 -f system, corresponding to the FROM argument. Frame number 2 -* (its current Frame) will describe the destination coordinate -c system, corresponding to the "to" parameter. The Mapping -f system, corresponding to the TO argument. The Mapping -* which inter-relates these two Frames will perform the -* required conversion between their respective coordinate -* systems. -* -* Note that a FrameSet may be used both as a Mapping and as a -* Frame. If the result is used as a Mapping (e.g. with -c astTran2), then it provides a means of converting coordinates -f AST_TRAN2), then it provides a means of converting coordinates -* from the source to the destination coordinate system (or -* vice versa if its inverse transformation is selected). If it -* is used as a Frame, its attributes will describe the -* destination coordinate system. - -* Applicability: -* DSBSpecFrame -* If the AlignSideBand attribute is non-zero, alignment occurs in the -* upper sideband expressed within the spectral system and standard of -* rest given by attributes AlignSystem and AlignStdOfRest. If -* AlignSideBand is zero, the two DSBSpecFrames are aligned as if -* they were simple SpecFrames (i.e. the SideBand is ignored). -* Frame -* This function applies to all Frames. Alignment occurs within the -* coordinate system given by attribute AlignSystem. -* FrameSet -c If either of the "from" or "to" parameters is a pointer to a -f If either of the FROM or TO arguments is a pointer to a -c FrameSet, then astConvert will attempt to convert from the -f FrameSet, then AST_CONVERT will attempt to convert from the -c coordinate system described by the current Frame of the "from" -f coordinate system described by the current Frame of the FROM -c FrameSet to that described by the current Frame of the "to" -f FrameSet to that described by the current Frame of the TO -* FrameSet. -* -* To achieve this, it will consider all of the Frames within -* each FrameSet as a possible way of reaching an intermediate -* coordinate system that can be used for the conversion. There -* is then the possibility that more than one conversion path -* may exist and, unless the choice is sufficiently restricted -c by the "domainlist" string, the sequence in which the Frames -f by the DOMAINLIST string, the sequence in which the Frames -* are considered can be important. In this case, the search -* for a conversion path proceeds as follows: -c - Each field in the "domainlist" string is considered in turn. -f - Each field in the DOMAINLIST string is considered in turn. -* - The Frames within each FrameSet are considered in a -* specific order: (1) the base Frame is always considered -* first, (2) after this come all the other Frames in -* Frame-index order (but omitting the base and current Frames), -* (3) the current Frame is always considered last. However, if -* either FrameSet's Invert attribute is set to a non-zero value -* (so that the FrameSet is inverted), then its Frames are -* considered in reverse order. (Note that this still means that -* the base Frame is considered first and the current Frame -* last, because the Invert value will also cause these Frames -* to swap places.) -* - All source Frames are first considered (in the appropriate -* order) for conversion to the first destination Frame. If no -* suitable intermediate coordinate system emerges, they are -* then considered again for conversion to the second -* destination Frame (in the appropriate order), and so on. -* - Generally, the first suitable intermediate coordinate -* system found is used. However, the overall Mapping between -* the source and destination coordinate systems is also -* examined. Preference is given to cases where both the -* forward and inverse transformations are defined (as indicated -* by the TranForward and TranInverse attributes). If only one -* transformation is defined, the forward one is preferred. -* - If the domain of the intermediate coordinate system matches -c the current "domainlist" field, the conversion path is -f the current DOMAINLIST field, the conversion path is -c accepted. Otherwise, the next "domainlist" field is considered -f accepted. Otherwise, the next DOMAINLIST field is considered -* and the process repeated. -* -* If conversion is possible, the Base attributes of the two -* FrameSets will be modified on exit to identify the Frames -* used to access the intermediate coordinate system which was -* finally accepted. -* -* Note that it is possible to force a particular Frame within a -* FrameSet to be used as the basis for the intermediate -* coordinate system, if it is suitable, by (a) focussing -* attention on -c it by specifying its domain in the "domainlist" string, or (b) -f it by specifying its domain in the DOMAINLIST string, or (b) -* making it the base Frame, since this is always considered -* first. -* SpecFrame -* Alignment occurs within the spectral system and standard of rest -* given by attributes AlignSystem and AlignStdOfRest. -* TimeFrame -* Alignment occurs within the time system and time scale given by -* attributes AlignSystem and AlignTimeScale. - -* Examples: -c cvt = astConvert( a, b, "" ); -f CVT = AST_CONVERT( A, B, ' ', STATUS ) -* Attempts to convert between the coordinate systems represented -c by "a" and "b" (assumed to be Frames). If successful, a FrameSet -f by A and B (assumed to be Frames). If successful, a FrameSet -c is returned via the "cvt" pointer which may be used to apply the -f is returned via the CVT pointer which may be used to apply the -c conversion to sets of coordinates (e.g. using astTran2). -f conversion to sets of coordinates (e.g. using AST_TRAN2). -c cvt = astConvert( astSkyFrame(""), astSkyFrame("Equinox=2005"), "" ); -f CVT = AST_CONVERT( AST_SKYFRAME( ' ', STATUS ), AST_SKYFRAME( 'Equinox=2005', STATUS ), ' ', STATUS ) -* Creates a FrameSet which describes precession in the default -* FK5 celestial coordinate system between equinoxes J2000 (also -c the default) and J2005. The returned "cvt" pointer may then -f the default) and J2005. The returned CVT pointer may then -c be passed to astTran2 to apply this precession correction to -f be passed to AST_TRAN2 to apply this precession correction to -* any number of coordinate values given in radians. -* -* Note that the returned FrameSet also contains information -* about how to format coordinate values. This means that -* setting its Report attribute to 1 is a simple way to obtain -* printed output (formatted in sexagesimal notation) to show -* the coordinate values before and after conversion. -c cvt = astConvert( a, b, "sky,detector," ); -f CVT = AST_CONVERT( A, B, 'SKY,DETECTOR,', STATUS ) -* Attempts to convert between the coordinate systems -c represented by the current Frames of "a" and "b" -f represented by the current Frames of A and B -* (now assumed to be FrameSets), via the intermediate "SKY" -* coordinate system. This, by default, is the Domain -* associated with a celestial coordinate system represented by -* a SkyFrame. -* -* If this fails (for example, because either FrameSet lacks -* celestial coordinate information), then the user-defined -* "DETECTOR" coordinate system is used instead. If this also -* fails, then all other possible ways of achieving conversion -* are considered before giving up. -* -c The returned pointer "cvt" indicates whether conversion was -f The returned pointer CVT indicates whether conversion was -* possible and will have the value AST__NULL if it was not. If -c conversion was possible, "cvt" will point at a new FrameSet -f conversion was possible, CVT will point at a new FrameSet -* describing the conversion. -* -* The Base attributes of the two FrameSets -c will be set by astConvert to indicate which of their Frames was -f will be set by AST_CONVERT to indicate which of their Frames was -* used for the intermediate coordinate system. This means that -* you can subsequently determine which coordinate system was -* used by enquiring the Domain attribute of either base Frame. - -* Notes: -* - The Mapping represented by the returned FrameSet results in -* alignment taking place in the coordinate system specified by the -c AlignSystem attribute of the "to" Frame. See the description of the -f AlignSystem attribute of the TO Frame. See the description of the -* AlignSystem attribute for further details. -* - When aligning (say) two images, which have been calibrated by -* attaching FrameSets to them, it is usually necessary to convert -* between the base Frames (representing "native" pixel -* coordinates) of both FrameSets. This may be achieved by -* inverting the FrameSets (e.g. using astInvert) so as to -* interchange their base and current Frames before using -* astConvert. -* - 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: -* This function is simply a wrap-up for the protected astConvertX -* method which performs the required processing but swaps the order -* of the first two arguments. 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 the first two arguments. -*/ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Invoke the "astConvertX" method with the first two arguments - swapped. */ - return astConvertX( to, from, domainlist ); -} - -static AstFrameSet *ConvertX( AstFrame *to, AstFrame *from, - const char *domainlist, int *status ) { -/* -*+ -* Name: -* astConvertX - -* Purpose: -* Determine how to convert between two coordinate systems. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* AstFrameSet *astConvertX( AstFrame *to, AstFrame *from, -* const char *domainlist ) - -* Class Membership: -* Frame method. - -* 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. -*- - -* Implementation Deficiencies: -* - This function's job is basically to negotiate with two Frames -* to try and find a mutually agreeable coordinate system for -* conversion. Ideally, it should be able to juggle the number of -* axes, etc. to do this. At present, however, the implementation -* is much simpler. This is adequate for the Frame classes which -* exist at the time of writing, but the implementation may need -* beefing up in future. -* - One likely problem is with attributes which default in both -* the source and destination Frames. This means they also default -* in the common coordinate system. If these default values were to -* differ when matching different target Frames, however, we would -* be in trouble, because the common coordinate system would not -* then be remaining constant. The longer-term solution to this is -* probably to provide some mechanism to "fix" all attribute values -* for a Frame, by taking any attributes that are un-set and -* explicitly setting a firm value (equal to the default) so they -* cannot then change. -*/ - -/* Local Variables: */ - AstFrameSet *result; /* Pointer to Mapping to be returned */ - AstFrame *ftmp; /* Pointer to returned Frame */ - AstMapping **map1_address; /* Location of first Mapping pointer */ - AstMapping **map2_address; /* Location of second Mapping pointer */ - AstMapping *common0; /* Initial common coordinate system */ - AstMapping *common1; /* Improved common coordinate system */ - AstMapping *common2; /* Final common coordinate system */ - AstMapping *frame1; /* Pointer to Frame for first match */ - AstMapping *frame2; /* Pointer to Frame for second match */ - AstMapping *from_map; /* Pointer to "from" Mapping */ - AstMapping *map; /* Pointer to conversion Mapping */ - AstMapping *result_map; /* Pointer to result Mapping */ - AstMapping *tmp; /* Temporary Mapping pointer */ - AstMapping *to_map; /* Pointer to "to" Mapping */ - char *domain; /* Pointer to result domain */ - char *domain_end; /* Pointer to null at end of domain */ - char *domainlist_copy; /* Pointer to copy of domainlist */ - int *axes1; /* Pointer to axis assignments */ - int *axes2; /* Pointer to axis assignments */ - int best_score; /* Score assigned to best match */ - int icom; /* Common coordinate system loop counter */ - int match1; /* First match succeeded? */ - int match2; /* Second match succeeded? */ - int match; /* Overall match found? */ - int perfect; /* Perfect match found? */ - int score; /* Score assigned to match */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Further initialisation. */ - result_map = NULL; - -/* Make a temporary copy of the domains list. */ - domainlist_copy = astStore( NULL, domainlist, - strlen( domainlist ) + (size_t) 1 ); - if ( astOK ) { - -/* Loop to inspect each comma-separated field in the domains list - until an error occurs, all the domains are used up, or a match is - found. */ - domain = domainlist_copy; - match = 0; - while ( astOK && domain && !match ) { - -/* Change the comma at the end of each field to a null to terminate - the domain. Then convert the domain to upper case and eliminate - white space. */ - if ( ( domain_end = strchr( domain, ',' ) ) ) *domain_end = '\0'; - CleanDomain( domain, status ); - -/* For any given domain, we will ignore imperfect matches in favour of - better ones by assigning a score to each match. Initialise the best - score value for the current domain. */ - best_score = -1; - -/* Loop to consider both the "to" and "from" Frames in turn as the - basis of a possible common coordinate system. Quit looping early if - an error occurs or a perfect match is found. */ - perfect = 0; - for ( icom = 0; astOK && !perfect && ( icom <= 1 ); icom++ ) { - -/* Make a copy of the Frame representing the initial guess at a common - coordinate system. We will use this to probe the other - Frame. Ensure that axes are not preserved (so that we convert to - the common axis number/order). */ - common0 = astCopy( icom ? from : to ); - astSetPreserveAxes( common0, 0 ); - -/* Also, if the current domain is not blank, set the Domain attribute (so - we will only find coordinate systems which match the current - "domainlist" field). */ - if ( *domain ) astSetDomain( common0, domain ); - -/* Obtain a pointer to the other Frame. */ - frame1 = astClone( icom ? to : from ); - -/* Set the address at which to store the resulting Mapping pointer. */ - map1_address = icom ? &to_map : &from_map; - -/* See if conversion from "frame1" to the common coordinate system is - possible. If successful, this results in a new approximation - ("common1") to the possible common coordinate system. */ - match1 = astMatch( common0, frame1, 1, &axes1, &axes2, - map1_address, &ftmp ); - common1 = (AstMapping *) ftmp; - -/* If successful, free memory allocated for the axis association - arrays, which are not needed. */ - if ( astOK && match1 ) { - axes1 = astFree( axes1 ); - axes2 = astFree( axes2 ); - -/* Using the improved approximation to the common coordinate system, - now test if conversion from the alternative Frame "frame2" is - possible. */ - frame2 = astClone( icom ? from : to ); - map2_address = icom ? &from_map : &to_map; - astSetPreserveAxes( common1, 0 ); - match2 = astMatch( common1, frame2, 1, &axes1, &axes2, - map2_address, &ftmp ); - common2 = (AstMapping *) ftmp; - -/* If successful, free memory allocated for the axis association - arrays, which are not needed. */ - if ( astOK && match2 ) { - axes1 = astFree( axes1 ); - axes2 = astFree( axes2 ); - -/* Invert the "to" Mapping and concatenate the two Mappings to - describe the conversion between the "from" and "to" Frames. Then - simplify the result. */ - astInvert( to_map ); - tmp = (AstMapping *) astCmpMap( from_map, to_map, 1, "", status ); - map = astSimplify( tmp ); - tmp = astAnnul( tmp ); - -/* Assign a score that favours Mappings with both transformations - available over those with only one, and Mappings with only a - forward transformation over those with only an inverse - transformation. */ - score = ( astGetTranForward( map ) ? 2 : 0 ) + - ( astGetTranInverse( map ) ? 1 : 0 ); - -/* If the new score is better than the previous one (or is the first - one), note that we have a possible match. */ - if ( astOK && ( score > best_score ) ) { - match = 1; - -/* Update the best score and note if it indicates a perfect match (in - which case we can stop searching at this point). */ - best_score = score; - perfect = ( best_score >= 3 ); - -/* Annul any previous result Mapping pointer and replace it with this - better one. */ - if ( result_map ) result_map = astAnnul( result_map ); - result_map = astClone( map ); - } - -/* Annul pointers to all the intermediate Objects. */ - map = astAnnul( map ); - common2 = astAnnul( common2 ); - *map2_address = astAnnul( *map2_address ); - } - frame2 = astAnnul( frame2 ); - common1 = astAnnul( common1 ); - *map1_address = astAnnul( *map1_address ); - } - frame1 = astAnnul( frame1 ); - common0 = astAnnul( common0 ); - } - -/* Go on to consider the next field in the domains list. */ - domain = domain_end ? domain_end + 1 : NULL; - } - } - -/* Free the domain list copy. */ - domainlist_copy = astFree( domainlist_copy ); - -/* If returning a result, build the result FrameSet. Then annul the - result Mapping pointer. */ - if ( result_map ) { - result = astFrameSet( from, "", status ); - astAddFrame( result, AST__BASE, result_map, to ); - result_map = astAnnul( result_map ); - } - -/* If an error occurred, annul the result FrameSet pointer. */ - if ( !astOK ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -static int DefaultMaxAxes( AstFrame *this, int *status ) { -/* -* Name: -* DefaultMaxAxes - -* Purpose: -* Obtain the MaxAxes attribute from a Frame structure, with defaulting. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int DefaultMaxAxes( AstFrame *this, int *status ) - -* Class Membership: -* Frame member function. - -* Description: -* This function inspects the max_axes component of a Frame structure and -* derives a value for the MaxAxes attribute. If the component's value -* indicates that the attribute has not been set, a suitable default is -* returned which is consistent with the state of the Frames's MinAxes -* attribute. - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The value to be used for the MaxAxes attribute. -*/ - -/* Local Variables. */ - int result; /* Result to be returned */ - int min_axes; /* Value of MinAxes attribute */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* If the Frame's max_axes component is set, return its value. */ - if ( this->max_axes != -INT_MAX ) { - result = this->max_axes; - -/* Otherwise, the preferred default value is the number of Frame axes. */ - } else { - result = astGetNaxes( this ); - -/* Before returning this value, check if the MinAxes attribute is set. If it - is, obtain its value. */ - if ( astTestMinAxes( this ) ) { - min_axes = astGetMinAxes( this ); - -/* If necessary, increase the MaxAxes default value so that it is not less than - MinAxes. */ - if ( result < min_axes ) result = min_axes; - } - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static int DefaultMinAxes( AstFrame *this, int *status ) { -/* -* Name: -* DefaultMinAxes - -* Purpose: -* Obtain the MinAxes attribute from a Frame structure, with defaulting. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int DefaultMinAxes( AstFrame *this, int *status ) - -* Class Membership: -* Frame member function. - -* Description: -* This function inspects the min_axes component of a Frame structure and -* derives a value for the MinAxes attribute. If the component's value -* indicates that the attribute has not been set, a suitable default is -* returned which is consistent with the state of the Frames's MaxAxes -* attribute. - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The value to be used for the MinAxes attribute. -*/ - -/* Local Variables: */ - int result; /* Result to be returned */ - int max_axes; /* Value of MaxAxes attribute */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* If the Frame's min_axes component is set, return its value. */ - if ( this->min_axes != -INT_MAX ) { - result = this->min_axes; - -/* Otherwise, the preferred default value is the number of Frame axes. */ - } else { - result = astGetNaxes( this ); - -/* Before returning this value, check if the MaxAxes attribute is set. If it - is, obtain its value. */ - if ( astTestMaxAxes( this ) ) { - max_axes = astGetMaxAxes( this ); - -/* If necessary, reduce the MinAxes default value so that it does not exceed - MaxAxes. */ - if ( result > max_axes ) result = max_axes; - } - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static double Distance( AstFrame *this, - const double point1[], const double point2[], int *status ) { -/* -*++ -* Name: -c astDistance -f AST_DISTANCE - -* Purpose: -* Calculate the distance between two points in a Frame. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c double astDistance( AstFrame *this, -c const double point1[], const double point2[] ) -f RESULT = AST_DISTANCE( THIS, POINT1, POINT2, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -* This function finds the distance between two points whose Frame -* coordinates are given. The distance calculated is that along -* the geodesic curve that joins the two points. -* -* For example, in a basic Frame, the distance calculated will be -* the Cartesian distance along the straight line joining the two -* points. For a more specialised Frame describing a sky coordinate -* system, however, it would be the distance along the great circle -* passing through two sky positions. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c point1 -f POINT1( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the first point. -c point2 -f POINT2( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* containing the coordinates of the second point. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astDistance -f AST_DISTANCE = DOUBLE PRECISION -* 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 -c invoked with the AST error status set, or if it should fail for -f invoked with STATUS set to an error value, or if it should fail for -* any reason. -*-- -*/ - -/* Local Variables: */ - double delta; /* Separation along an axis */ - double result; /* Result value to return */ - int axis; /* Loop counter for axes */ - int naxes; /* Number of Frame axes */ - -/* Initialise. */ - result = AST__BAD; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain the number of Frame axes. */ - naxes = astGetNaxes( this ); - if ( astOK ) { - -/* Loop to determine the Cartesian distance between the points. */ - result = 0.0; - for ( axis = 0; axis < naxes; axis++ ) { - -/* If any of the coordinates supplied is bad, set the distance to be - bad and quit looping. */ - if ( ( point1[ axis ] == AST__BAD ) || - ( point2[ axis ] == AST__BAD ) ) { - result = AST__BAD; - break; - -/* Otherwise, accumulate the sum of squared separations along each - axis. */ - } else { - delta = point1[ axis ] - point2[ axis ]; - result += ( delta * delta ); - } - } - -/* Take the square root to find the distance (if valid). */ - if ( result != AST__BAD ) result = sqrt( result ); - } - -/* Return the result. */ - return result; -} - -static int DoNotSimplify( AstMapping *this, int *status ) { -/* -* Name: -* DoNotSimplify - -* Purpose: -* Check if a Mapping is appropriate for simplification. - -* Type: -* Private function. - -* Synopsis: -* #include "object.h" -* int DoNotSImplify( AstMapping *this ); - -* Class Membership: -* CmpMap member function (over-rides the astDoNotSimplify protected -* method inherited from the parent class). - -* Description: -* This function returns a flag indivating if the supplied Mapping is -* appropriate for simplification. - -* Parameters: -* this -* Pointer to the Mapping. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Non-zero if the supplied Mapping is not appropriate for -* simplification, and zero otherwise. - -* Notes: -* - A value of 0 will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. - -*/ - -/* Unlike basic Mappings, Frames that have a set value for the Ident - can be simplified. So always return zero. */ - return 0; -} - -static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { -/* -* Name: -* Equal - -* Purpose: -* Test if two Frames are equivalent. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int Equal( AstObject *this, AstObject *that, int *status ) - -* Class Membership: -* Frame member function (over-rides the astEqual protected -* method inherited from the Mapping class). - -* Description: -* This function returns a boolean result (0 or 1) to indicate whether -* two Frames are equivalent. - -* Parameters: -* this -* Pointer to the first Frame. -* that -* Pointer to the second Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* One if the Frames are equivalent, zero otherwise. - -* Notes: -* - The two Frames are considered equivalent if the Mapping between -* them is a UnitMap. -* - 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 *that; /* Pointer to the second Frame structure */ - AstFrame *this; /* Pointer to the first Frame structure */ - AstFrameSet *fs; /* FrameSet connecting the two Frames */ - AstMapping *map1; /* Mapping connecting the two Frames */ - AstMapping *map2; /* Simplified mapping connecting two Frames */ - int result; /* Result value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Checks that the second object is of the same class as the first . */ - if( !strcmp( astGetClass( this_object ), astGetClass( that_object ) ) ){ - -/* Obtain pointers to the two Frame structures. */ - this = (AstFrame *) this_object; - that = (AstFrame *) that_object; - -/* Get the Mapping between them, and see if it is a UnitMap. */ - fs = astConvert( that, this, "" ); - if( fs ) { - map1 = astGetMapping( fs, AST__BASE, AST__CURRENT ); - map2 = astSimplify( map1 ); - result = astIsAUnitMap( map2 ); - map1 = astAnnul( map1 ); - map2 = astAnnul( map2 ); - fs = astAnnul( fs ); - } - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result, */ - return result; -} - -static int Fields( AstFrame *this, int axis, const char *fmt, - const char *str, int maxfld, char **fields, - int *nc, double *val, int *status ) { -/* -*+ -* Name: -* astFields - -* Purpose: -* Identify numerical fields within a formatted Axis value. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astFields( AstFrame *this, int axis, const char *fmt, -* const char *str, int maxfld, char **fields, -* int *nc, double *val ) - -* Class Membership: -* Frame method. - -* Description: -* This function identifies the numerical fields within a Frame axis -* value that has been formatted using astAxisFormat. It assumes that -* the value was formatted using the supplied format string. It also -* returns the equivalent floating point value. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The number of the Frame 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 used when creating "str". -* str -* Pointer to a constant null-terminated string containing the -* formatted value. -* maxfld -* The maximum number of fields to identify within "str". -* fields -* A pointer to an array of at least "maxfld" character pointers. -* Each element is returned holding a pointer to the start of the -* corresponding field in "str" (in the order in which they occur -* within "str"), or NULL if no corresponding field can be found. -* nc -* A pointer to an array of at least "maxfld" integers. Each -* element is returned holding the number of characters in the -* corresponding field, or zero if no corresponding field can be -* found. -* val -* Pointer to a location at which to store the value -* equivalent to the returned field values. If this is NULL, -* it is ignored. - -* Returned Value: -* The number of fields succesfully identified and returned. - -* Notes: -* - Leading and trailing spaces are ignored. -* - If the formatted value is not consistent with the supplied format -* string, then a value of zero will be returned, "fields" will be -* returned holding NULLs, "nc" will be returned holding zeros, and -* "val" is returned holding VAL__BAD. -* - Fields are counted from the start of the formatted string. If the -* string contains more than "maxfld" fields, then trailing fields are -* ignored. -* - If this function is invoked with the global error status set, or -* if it should fail for any reason, then a value of zero will be returned -* as the function value, and "fields", "nc" and "val" will be returned -* holding their supplied values -*- -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - int result; /* Result field count to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Validate the axis index and obtain a pointer to the required - Axis. */ - (void) astValidateAxis( this, axis, 1, "astFields" ); - ax = astGetAxis( this, axis ); - -/* Invoke the Axis astAxisFields method to perform the processing. */ - result = astAxisFields( ax, fmt, str, maxfld, fields, nc, val ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* If an error occurred, clear the returned value. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static AstFrameSet *FindFrame( AstFrame *target, AstFrame *template, - const char *domainlist, int *status ) { -/* -*++ -* Name: -c astFindFrame -f AST_FINDFRAME - -* Purpose: -* Find a coordinate system with specified characteristics. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c AstFrameSet *astFindFrame( AstFrame *target, AstFrame *template, -c const char *domainlist ) -f RESULT = AST_FINDFRAME( TARGET, TEMPLATE, DOMAINLIST, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -* This function uses a "template" Frame to search another Frame -* (or FrameSet) 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. -* -* This function is provided to help answer general questions about -* coordinate systems, such as typically arise when coordinate -* information is imported into a program as part of an initially -* unknown dataset. For example: -* - Is there a wavelength scale? -* - Is there a 2-dimensional coordinate system? -* - Is there a celestial coordinate system? -* - Can I plot the data in ecliptic coordinates? -* -* You can also use this function as a means of reconciling a -* user's preference for a particular coordinate system (for -* example, what type of axes to draw) with what is actually -* possible given the coordinate information available. -* -* To perform a search, you supply a "target" Frame (or FrameSet) -* which represents the set of coordinate systems to be searched. -* If a basic Frame is given as the target, this set of coordinate -* systems consists of the one described by this Frame, plus all -* other "virtual" coordinate systems which can potentially be -* reached from it by applying built-in conversions (for example, -* any of the celestial coordinate conversions known to the AST -* library would constitute a "built-in" conversion). If a FrameSet -* is given as the target, the set of coordinate systems to be -* searched consists of the union of those represented by all the -* individual Frames within it. -* -* To select from this large set of possible coordinate systems, -* you supply a "template" Frame which is an instance of the type -* of Frame you are looking for. Effectively, you then ask the -* function to "find a coordinate system that looks like this". -* -* You can make your request more or less specific by setting -* attribute values for the template Frame. If a particular -* attribute is set in the template, then the function will only -* find coordinate systems which have exactly the same value for -* that attribute. If you leave a template attribute un-set, -* however, then the function has discretion about the value the -* attribute should have in any coordinate system it finds. The -* attribute will then take its value from one of the actual -* (rather than virtual) coordinate systems in the target. If the -* target is a FrameSet, its Current attribute will be modified to -* indicate which of its Frames was used for this purpose. -* -* The result of this process is a coordinate system represented by -* a hybrid Frame which acquires some attributes from the template -* (but only if they were set) and the remainder from the -* target. This represents the "best compromise" between what you -* asked for and what was available. A Mapping is then generated -* which converts from the target coordinate system to this hybrid -* one, and the returned FrameSet encapsulates all of this -* information. - -* Parameters: -c target -f TARGET = INTEGER (Given) -* Pointer to the target Frame (or FrameSet). -* -* Note that if a FrameSet is supplied (and a suitable -* coordinate system is found), then its Current attribute will -* be modified to indicate which Frame was used to obtain -* attribute values which were not specified by the template. -* This Frame will, in some sense, represent the "closest" -* non-virtual coordinate system to the one you requested. -c template -f TEMPLATE = INTEGER (Given) -* Pointer to the template Frame, which should be an instance of -* the type of Frame you wish to find. If you wanted to find a -* Frame describing a celestial coordinate system, for example, -* then you might use a SkyFrame here. See the "Examples" -* section for more ideas. -c domainlist -f DOMAINLIST = CHARACTER * ( * ) (Given) -c Pointer to a null-terminated character string containing a -f A 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, -c you should supply an empty string. -f you should supply a blank string. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astFindFrame() -f AST_FINDFRAME = INTEGER -* 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 (base Frame of 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 that a FrameSet may be used both as a Mapping and as a -* Frame. If the result is used as a Mapping (e.g. with -* astTran2), then it provides a means of converting coordinates -* from the target coordinate system into the new coordinate -* system that was found (and vice versa if its inverse -* transformation is selected). If it is used as a Frame, its -* attributes will describe the new coordinate system. - -* Applicability: -* Frame -* This function applies to all Frames. -* FrameSet -* If the target is a FrameSet, the possibility exists that -* several of the Frames within it might be matched by the -* template. Unless the choice is sufficiently restricted by -c the "domainlist" string, the sequence in which Frames are -f the DOMAINLIST string, the sequence in which Frames are -* searched can then become important. In this case, the search -* proceeds as follows: -c - Each field in the "domainlist" string is considered in turn. -f - Each field in the DOMAINLIST string is considered in turn. -* - An attempt is made to match the template to each of the -* target's Frames in the order: (1) the current Frame, (2) the -* base Frame, (3) each remaining Frame in the order of being -* added to the target FrameSet. -* - Generally, the first match found is used. However, the -* Mapping between the target coordinate system and the -* resulting Frame is also examined. Preference is given to -* cases where both the forward and inverse transformations are -* defined (as indicated by the TranForward and TranInverse -* attributes). If only one transformation is defined, the -* forward one is preferred. -* - If a match is found and the domain of the resulting Frame also -c matches the current "domainlist" field, it is -f matches the current DOMAINLIST field, it is -c accepted. Otherwise, the next "domainlist" field is considered -f accepted. Otherwise, the next DOMAINLIST field is considered -* and the process repeated. -* -* If a suitable coordinate system is found, the Current -* attribute of the target FrameSet will be modified on exit to -* identify the Frame whose match with the target was eventually -* accepted. - -* Examples: -c result = astFindFrame( target, astFrame( 3, "" ), "" ); -f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 3, ' ', STATUS ), ' ', STATUS ) -* Searches for a 3-dimensional coordinate system in the target -* Frame (or FrameSet). No attributes have been set in the -c template Frame (created by astFrame), so no restriction has -f template Frame (created by AST_FRAME), so no restriction has -* been placed on the required coordinate system, other than -* that it should have 3 dimensions. The first suitable Frame -c found will be returned as part of the "result" FrameSet. -f found will be returned as part of the RESULT FrameSet. -c result = astFindFrame( target, astSkyFrame( "" ), "" ); -f RESULT = AST_FINDFRAME( TARGET, AST_SKYFRAME( ' ', STATUS ), ' ', STATUS ) -* Searches for a celestial coordinate system in the target -* Frame (or FrameSet). The type of celestial coordinate system -c is unspecified, so astFindFrame will return the first one -f is unspecified, so AST_FINDFRAME will return the first one -c found as part of the "result" FrameSet. If the target is -f found as part of the RESULT FrameSet. If the target is -* a FrameSet, then its Current attribute will be updated to -* identify the Frame that was used. -* -* If no celestial coordinate system can be found, a value of -* AST__NULL will be returned without error. -c result = astFindFrame( target, astSkyFrame( "MaxAxes=100" ), "" ); -f RESULT = AST_FINDFRAME( TARGET, AST_SKYFRAME( 'MaxAxes=100', STATUS ), ' ', STATUS ) -* This is like the last example, except that in the event of the -* target being a CmpFrame, the component Frames encapsulated by the -* CmpFrame will be searched for a SkyFrame. If found, the returned -* Mapping will included a PermMap which selects the required axes -* from the target CmpFrame. -* -* This is acomplished by setting the MaxAxes attribute of the -* template SkyFrame to a large number (larger than or equal to the -* number of axes in the target CmpFrame). This allows the SkyFrame -* to be used as a match for Frames containing from 2 to 100 axes. -c result = astFindFrame( target, astSkyFrame( "System=FK5" ), "" ); -f RESULT = AST_FINDFRAME( TARGET, AST_SKYFRAME( 'System=FK5', STATUS ), ' ', STATUS ) -* Searches for an equatorial (FK5) coordinate system in the -* target. The Equinox value for the coordinate system has not -* been specified, so will be obtained from the target. If the -* target is a FrameSet, its Current attribute will be updated -* to indicate which SkyFrame was used to obtain this value. -c result = astFindFrame( target, astFrame( 2, "" ), "sky,pixel," ); -f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 2, ' ', STATUS ), 'SKY,PIXEL,', STATUS ) -* Searches for a 2-dimensional coordinate system in the -* target. Initially, a search is made for a suitable coordinate -* system whose Domain attribute has the value "SKY". If this -* search fails, a search is then made for one with the domain -* "PIXEL". If this also fails, then any 2-dimensional -c coordinate system is returned as part of the "result" -f coordinate system is returned as part of the RESULT -* FrameSet. -* -* Only if no 2-dimensional coordinate systems can be reached by -* applying built-in conversions to any of the Frames in the -* target will a value of AST__NULL be returned. -c result = astFindFrame( target, astFrame( 1, "Domain=WAVELENGTH" ), "" ); -f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 1, 'Domain=WAVELENGTH', STATUS ), ' ', STATUS ) -* Searches for any 1-dimensional coordinate system in the -* target which has the domain "WAVELENGTH". -c result = astFindFrame( target, astFrame( 1, "" ), "wavelength" ); -f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 1, ' ', STATUS ), 'WAVELENGTH', STATUS ) -* This example has exactly the same effect as that above. It -* illustrates the equivalence of the template's Domain attribute -c and the fields in the "domainlist" string. -f and the fields in the DOMAINLIST string. -c result = astFindFrame( target, astFrame( 1, "MaxAxes=3" ), "" ); -f RESULT = AST_FINDFRAME( TARGET, AST_FRAME( 1, 'MaxAxes=3', STATUS ), ' ', STATUS ) -* This is a more advanced example which will search for any -* coordinate system in the target having 1, 2 or 3 -c dimensions. The Frame returned (as part of the "result" -f dimensions. The Frame returned (as part of the RESULT -* FrameSet) will always be 1-dimensional, but will be related -* to the coordinate system that was found by a suitable Mapping -* (e.g. a PermMap) which simply extracts the first axis. -* -* If we had wanted a Frame representing the actual (1, 2 or -* 3-dimensional) coordinate system found, we could set the -* PreserveAxes attribute to a non-zero value in the template. -c result = astFindFrame( target, astSkyFrame( "Permute=0" ), "" ); -f RESULT = AST_FINDFRAME( TARGET, AST_SKYFRAME( 'Permute=0', STATUS ), ' ', STATUS ) -* Searches for any celestial coordinate system in the target, -* but only finds one if its axes are in the conventional -* (longitude,latitude) order and have not been permuted -c (e.g. with astPermAxes). -f (e.g. with AST_PERMAXES). - -* Notes: -* - The Mapping represented by the returned FrameSet results in -* alignment taking place in the coordinate system specified by the -c AlignSystem attribute of the "template" Frame. See the description -f AlignSystem attribute of the TEMPLATE Frame. See the description -* of the AlignSystem attribute for further details. -* - Beware of setting the Domain attribute of the template and then -c using a "domainlist" string which does not include the template's domain -f using a DOMAINLIST string which does not include the template's domain -* (or a blank field). If you do so, no coordinate system will be -* found. -* - 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. - -* More on Using Templates: -* A Frame (describing a coordinate system) will be found by this -* function if (a) it is "matched" by the template you supply, and -c (b) the value of its Domain attribute appears in the "domainlist" -f (b) the value of its Domain attribute appears in the DOMAINLIST -* string (except that a blank field in this string permits any -* domain). A successful match by the template depends on a number -* of criteria, as outlined below: -* - In general, a template will only match another Frame which -* belongs to the same class as the template, or to a derived (more -* specialised) class. For example, a SkyFrame template will match -* any other SkyFrame, but will not match a basic -* Frame. Conversely, a basic Frame template will match any class -* of Frame. -* - The exception to this is that a Frame of any class can be used to -* match a CmpFrame, if that CmpFrame contains a Frame of the same -* class as the template. Note however, the MaxAxes and MinAxes -* attributes of the template must be set to suitable values to allow -* it to match the CmpFrame. That is, the MinAxes attribute must be -* less than or equal to the number of axes in the target, and the MaxAxes -* attribute must be greater than or equal to the number of axes in -* the target. -* - If using a CmpFrame as a template frame, the MinAxes and MaxAxes -* for the template are determined by the MinAxes and MaxAxes values of -* the component Frames within the template. So if you want a template -* CmpFrame to be able to match Frames with different numbers of axes, -* then you must set the MaxAxes and/or MinAxes attributes in the component -* template Frames, before combining them together into the template -* CmpFrame. -* - If a template has a value set for any of its main attributes, then -* it will only match Frames which have an identical value for that -* attribute (or which can be transformed, using a built-in -* conversion, so that they have the required value for that -* attribute). If any attribute in the template is un-set, however, -* then Frames are matched regardless of the value they may have -* for that attribute. You may therefore make a template more or -* less specific by choosing the attributes for which you set -* values. This requirement does not apply to 'descriptive' attributes -* such as titles, labels, symbols, etc. -* - An important application of this principle involves the Domain -* attribute. Setting the Domain attribute of the template has the -* effect of restricting the search to a particular type of Frame -* (with the domain you specify). Conversely, if the Domain -* attribute is not set in the template, then the domain of the -* Frame found is not relevant, so all Frames are searched. Note -* that the -c "domainlist" string provides an alternative way of restricting the -f DOMAINLIST string provides an alternative way of restricting the -* search in the same manner, but is a more convenient interface if -* you wish to search automatically for another domain if the first -* search fails. -* - Normally, a template will only match a Frame which has the -* same number of axes as itself. However, for some classes of -* template, this default behaviour may be changed by means of the -* MinAxes, MaxAxes and MatchEnd attributes. In addition, the -* behaviour of a template may be influenced by its Permute and -* PreserveAxes attributes, which control whether it matches Frames -* whose axes have been permuted, and whether this permutation is -* retained in the Frame which is returned (as opposed to returning -* the axes in the order specified in the template, which is the -* default behaviour). You should consult the descriptions of these -* attributes for details of this more advanced use of templates. -*-- -*/ - -/* Local Variables: */ - AstFrame *frame; /* Pointer to result Frame */ - AstFrameSet *result; /* Pointer to result FrameSet */ - AstMapping *map; /* Pointer to result Mapping */ - AstMapping *tmp; /* Temporary Mapping pointer */ - char *domain_copy; /* Pointer to copy of result domain */ - char *domainlist_copy; /* Pointer to copy of domains list */ - const char *domain; /* Pointer to result Domain value */ - int *target_axes; /* Pointer to target axis assignments */ - int *template_axes; /* Pointer to template axis assignments */ - int i; /* Loop counter for characters */ - int j; /* Character index */ - int match; /* Template matched target? */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Allocate space to store a copy of the domains list, with added - commas. */ - domainlist_copy = astMalloc( strlen( domainlist ) + (size_t) 3 ); - if ( astOK ) { - -/* Make a copy of the domains list, with an extra comma added at each - end. Also remove all white space and convert to upper case. */ - domainlist_copy[ 0 ] = ','; - for ( i = 0, j = 1; domainlist[ i ]; i++ ) { - if ( !isspace( domainlist[ i ] ) ) { - domainlist_copy[ j++ ] = toupper( domainlist[ i ] ); - } - } - domainlist_copy[ j++ ] = ','; - domainlist_copy[ j ] = '\0'; - -/* Invoke the protected astMatch method associated with the template - Frame. This matches the template to the target and returns - information about how to convert between the target and the Frame - it found (if any). */ - match = astMatch( template, target, 0, - &template_axes, &target_axes, &map, &frame ); - -/* If successful, obtain a pointer to the Domain string of the result - Frame. Allocate space for a copy of this string, with added - commas. */ - if ( match && astOK ) { - domain = astGetDomain( frame ); - if ( astOK ) { - domain_copy = astMalloc( strlen( domain ) + (size_t) 3 ); - if ( astOK ) { - -/* Make a copy of the domain, adding an extra comma at each end. */ - domain_copy[ 0 ] = ','; - for ( i = 0, j = 1; domain[ i ]; i++ ) { - domain_copy[ j++ ] = domain[ i ]; - } - domain_copy[ j++ ] = ','; - domain_copy[ j ] = '\0'; - -/* Test if the domain appears in the domains list (with added - commas). If not, test if a blank domain (which permits the result - Frame to have any Domain) appears instead. */ - if ( strstr( domainlist_copy, domain_copy ) || - strstr( domainlist_copy, ",," ) ) { - -/* If the result Frame is acceptable, simplify the result Mapping. */ - tmp = astSimplify( map ); - map = astAnnul( map ); - map = tmp; - -/* Build the result FrameSet. */ - result = astFrameSet( target, "", status ); - astAddFrame( result, AST__BASE, map, frame ); - } - } - -/* Free the copy of the result domain. */ - domain_copy = astFree( domain_copy ); - } - -/* Free space and annul pointers allocated by astMatch. */ - template_axes = astFree( template_axes ); - target_axes = astFree( target_axes ); - map = astAnnul( map ); - frame = astAnnul( frame ); - } - } - -/* Free the copy of the domains list. */ - domainlist_copy = astFree( domainlist_copy ); - -/* If an error occurred, annul any result pointer. */ - if ( !astOK && result ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -const char *astFmtDecimalYr_( double year, int digits, int *status ) { -/* -*+ -* Name: -* astFmtDecimalYr - -* Purpose: -* Format an epoch expressed in years as a decimal string. - -* Type: -* Protected function. - -* Synopsis: -* #include "frame.h" -* const char *astFmtDecimalYr( double year, int digits ) - -* Class Membership: -* Frame member function. - -* Description: -* This function formats an epoch expressed in years as a decimal string -* and returns a pointer to the result. It is intended for formatting -* Frame Epoch values, etc, for display. - -* Parameters: -* year -* The epoch to be formatted. -* digits -* The number of digits of precision required. - -* Returned Value: -* Pointer to a null terminated string containing the formatted value. - -* Notes: -* - The result string is stored in static memory and may be -* over-written by a subsequent invocation of this function. -* - A NULL pointer is returned if this function is invoked with -* the global error status set or if it should fail for any reason. -*- -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - int nc; /* Number of characters in buffer */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(NULL); - -/* Limit the precision to what is meaningful. */ - digits = ( digits > AST__DBL_DIG ) ? AST__DBL_DIG : digits; - -/* Format the year value. Use "g" format to avoid buffer overflow and - to get useful diagnostic output if a silly value is given. */ - nc = sprintf( astfmtdecimalyr_buff, "%#.*g", digits, year ); - -/* Loop to remove redundant zeros from the end of the result. */ - while ( astfmtdecimalyr_buff[ --nc ] == '0' ) astfmtdecimalyr_buff[ nc ] = '\0'; - -/* If the last character is now a decimal point, put back one zero. */ - if ( astfmtdecimalyr_buff[ nc ] == '.' ) { - astfmtdecimalyr_buff[ ++nc ] = '0'; - astfmtdecimalyr_buff[ ++nc ] = '\0'; - } - -/* Return the result. */ - return astfmtdecimalyr_buff; -} - -static const char *Format( AstFrame *this, int axis, double value, int *status ) { -/* -*+ -* Name: -* astFormat - -* Purpose: -* Format a coordinate value for a Frame axis. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* const char *astFormat( AstFrame *this, int axis, double value ) - -* Class Membership: -* Frame method. - -* Description: -* This function returns a pointer to a string containing the -* formatted (character) version of a coordinate value for a Frame -* axis. The formatting applied is determined by the Frame's -* attributes and, in particular, by any Format attribute string -* that has been set for the axis. A suitable default format will -* be applied if necessary. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The number of the Frame axis for which formatting is to be -* performed (axis numbering starts at zero for the first axis). -* value -* The coordinate value to be formatted. - -* 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 Frame, 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 Frame. 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. -*- - -* Implementation Notes: -* - This function implements the basic astFormat method available -* via the protected interface to the Frame class. The public -* interface to this method is provided by the astFormatId_ -* function. -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - const char *result; /* Pointer value to return */ - int digits_set; /* Axis Digits attribute set? */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Validate the axis index and obtain a pointer to the required Axis. */ - (void) astValidateAxis( this, axis, 1, "astFormat" ); - ax = astGetAxis( this, axis ); - -/* Test if any Axis attributes which may affect the result are undefined (i.e. - have not been explicitly set). If so, we over-ride them, giving them - temporary values dictated by the Frame. Only the Digits attribute is - relevant here. */ - digits_set = astTestAxisDigits( ax ); - if ( !digits_set ) astSetAxisDigits( ax, astGetDigits( this ) ); - -/* Format the value. */ - result = astAxisFormat( ax, value ); - -/* Clear any Axis attributes that were temporarily over-ridden. */ - if ( !digits_set ) astClearAxisDigits( ax ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = NULL; - -/* Return the result. */ - return result; -} - -static AstPointSet *FrameGrid( AstFrame *this, int size, const double *lbnd, - const double *ubnd, int *status ){ -/* -*+ -* Name: -* astFrameGrid - -* Purpose: -* Return a grid of points covering a rectangular area of a Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* AstPointSet *astFrameGrid( AstFrame *this_frame, int size, -* const double *lbnd, const double *ubnd ) - -* Class Membership: -* Frame method. - -* Description: -* This function returns a PointSet containing positions spread -* approximately evenly throughtout a specified rectangular area of -* the Frame. - -* Parameters: -* this -* Pointer to the Frame. -* size -* The preferred number of points in the returned PointSet. The -* actual number of points in the returned PointSet may be -* different, but an attempt is made to stick reasonably closely to -* the supplied value. -* lbnd -* Pointer to an array holding the lower bound of the rectangular -* area on each Frame axis. The array should have one element for -* each Frame axis. -* ubnd -* Pointer to an array holding the upper bound of the rectangular -* area on each Frame axis. The array should have one element for -* each Frame axis. - -* Returned Value: -* A pointer to a new PointSet holding the grid of points. - -* Notes: -* - A NULL pointer is returned if an error occurs. -*- -*/ - -/* Local Variables: */ - AstPointSet *result; - const char *unit; - double **ptr; - double *gmean; - double *step; - int *maxi; - int *nsame; - int *ntick; - int *pi; - int bad; - int iax; - int ipp; - int jax; - int naxes; - int np; - int ntick0; - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get the number of axes in the Frame. */ - naxes = astGetNaxes( this ); - -/* Allocate an array to hold the number of ticks along each axis. */ - ntick = astMalloc( sizeof(int)*naxes ); - -/* Allocate an array to hold the geometric mean of the lengths of the - axes that have the same units as the current axis. */ - gmean = astMalloc( naxes*sizeof(double) ); - -/* Allocate an array to hold the number of axes that share the same unit. */ - nsame = astMalloc( naxes*sizeof(int) ); - if( astOK ) { - -/* For each axis, find the total number of axes in the Frame that have - the same unit string. Also, find the product of the lengths of these - axes. */ - bad = 0; - for( iax = 0; iax < naxes; iax++ ) { - nsame[ iax ] = 1; - - if( ubnd[ iax ] == AST__BAD && - lbnd[ iax ] == AST__BAD ) { - bad = 1; - break; - } - - gmean[ iax ] = ubnd[ iax ] - lbnd[ iax ]; - unit = astGetUnit( this, iax ); - for( jax = 0; jax < naxes; jax++ ) { - if( jax != iax ) { - if( astOK && !strcmp( unit, astGetUnit( this, jax ) ) ) { - nsame[ iax ]++; - gmean[ iax ] *= ubnd[ jax ] - lbnd[ jax ]; - } - } - } - } - -/* Do nothing if any bad bounds were supplied, or if the size is less - than 1. */ - if( !bad && size >= 1 ) { - -/* Get the nominal number of ticks per axis. */ - ntick0 = pow( size, 1.0/(double)naxes ); - if( ntick0 < 2 ) ntick0 = 2; - -/* Convert the dimension products into geometric means. */ - for( iax = 0; iax < naxes; iax++ ) { - gmean[ iax ] = pow( fabs(gmean[ iax ]), 1.0/(double)nsame[ iax ] ); - } - -/* The number of ticks to use on each axis is equal to the nominal number - multiplied by the ratio of the axis length to the geometric mean of the - axis lengths that sahare the same unit string. This gives more ticks - on the longer axes within any group of common-unit axes, whilst - retaining the overall number of ticks (roughly). Also find the total - number of points. */ - np = 1; - for( iax = 0; iax < naxes; iax++ ) { - ntick[ iax ] = ntick0*( ubnd[ iax ] - lbnd[ iax ] )/gmean[ iax ]; - if( ntick[ iax ] < 2 ) ntick[ iax ] = 2; - np *= ntick[ iax ]; - } - -/* Create a PointSet large enough to hold this many points. */ - result = astPointSet( np, naxes, " ", status ); - ptr = astGetPoints( result ); - -/* Allocate memory to hold the max indices on each axis. */ - maxi = astMalloc( sizeof( int )*(size_t) naxes ); - -/* Allocate memory to hold the indices of the current position.*/ - pi = astMalloc( sizeof( int )*(size_t) naxes ); - -/* Allocate memory to hold the step size for each axis. */ - step = astMalloc( sizeof( double )*(size_t) naxes ); - if( astOK ) { - -/* For every axis, set up the step size, initialise the current position to - the lower bound, and store a modified upper limit which includes some - safety marging to allow for rounding errors. */ - for( iax = 0; iax < naxes; iax++ ) { - step[ iax ] = ( ubnd[ iax ] - lbnd[ iax ] )/( ntick[ iax ] - 1 ); - pi[ iax ] = 0; - maxi[ iax ] = ntick[ iax ] - 1; - } - -/* Initialise the index of the next position to store. */ - ipp = 0; - -/* Loop round adding points to the array until the whole volume has been - done. */ - iax = 0; - while( iax < naxes ) { - -/* Add the current point to the supplied array, and increment the index of - the next point to add. */ - for( iax = 0; iax < naxes; iax++ ) { - ptr[ iax ][ ipp ] = lbnd[ iax ] + pi[ iax ]*step[ iax ]; - } - ipp++; - -/* We now move the current position on to the next sample */ - iax = 0; - while( iax < naxes ) { - pi[ iax ]++; - if( pi[ iax ] > maxi[ iax ] ) { - pi[ iax ] = 0; - iax++; - } else { - break; - } - } - } - } - -/* Free resources. */ - maxi = astFree( maxi ); - pi = astFree( pi ); - step = astFree( step ); - -/* Report error if supplied values were bad. */ - } else if( astOK ) { - if( bad ) { - astError( AST__ATTIN, "astFrameGrid(%s): One of more of the " - "supplied bounds is AST__BAD (programming error).", - status, astGetClass( this ) ); - } else if( size < 1 ) { - astError( AST__ATTIN, "astFrameGrid(%s): The supplied grid " - "size (%d) is invalid (programming error).", - status, astGetClass( this ), size ); - } - } - } - -/* Free resources. */ - ntick = astFree( ntick ); - nsame = astFree( nsame ); - gmean = astFree( gmean ); - -/* Annul the returned PointSet if an error has occurred. */ - if( !astOK ) result = astAnnul( result ); - -/* Return the PointSet holding the grid. */ - return result; -} - -static double Gap( AstFrame *this, int axis, double gap, int *ntick, int *status ) { -/* -*+ -* Name: -* astGap - -* Purpose: -* Find a "nice" gap for tabulating Frame axis values. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* double astGap( AstFrame *this, int axis, double gap, int *ntick ) - -* Class Membership: -* Frame method. - -* Description: -* This function returns a gap size which produces a nicely spaced -* series of formatted values for a Frame 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 Frame. -* 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. - -* 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: */ - AstAxis *ax; /* Pointer to Axis object */ - double result; /* The nice gap value */ - -/* Check the global error status. */ - if ( !astOK ) return 0.0; - -/* Validate the axis index and obtain a pointer to the required - Axis. */ - (void) astValidateAxis( this, axis, 1, "astGap" ); - ax = astGetAxis( this, axis ); - -/* Find the gap. */ - result = astAxisGap( ax, gap, ntick ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0.0; - -/* Return the result. */ - return result; -} - -static int GetActiveUnit( AstFrame *this, int *status ){ -/* -*++ -* Name: -c astGetActiveUnit -f AST_GETACTIVEUNIT - -* Purpose: -* Determines how the Unit attribute will be used. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c int astGetActiveUnit( AstFrame *this ) -f RESULT = AST_GETACTIVEUNIT( THIS, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function -f This routine -* returns the current value of the ActiveUnit flag for a Frame. See -c the description of the astSetActiveUnit function -f the description of the AST_SETACTIVEUNIT routine -* for a description of the ActiveUnit flag. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astGetActiveUnit -f AST_GETACTIVEUNIT = LOGICAL -* The current value of the ActiveUnit flag. - -* Notes: -c - A zero value will be returned if this function is -c invoked with the AST error status set, or if it should fail for -f - A value of .FALSE. will be returned if this function is -f invoked with STATUS set to an error value, or if it should fail for -* any reason. -*-- -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to axis structure */ - int i; /* Index of axis in Frame */ - int has_skyaxis; /* Does Frame contain any SkyAxes? */ - int nax; /* Number of axes in Frame */ - int result; /* The returned value */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* See if the Frame contains a SkyAxis. */ - has_skyaxis = 0; - nax = astGetNaxes( this ); - for( i = 0; i < nax; i++ ) { - ax = astGetAxis( this, i ); - if( astIsASkyAxis( ax ) ) has_skyaxis = 1; - ax = astAnnul( ax ); - } - -/* If the Frame contains a SkyAxis the ActiveUnit flag is always zero. */ - if( !has_skyaxis ) { - -/* Otherwise, get the value from the Frame. If it has not yet been assigned a - value return the value zero. */ - result = this->active_unit; - if( result == -INT_MAX ) 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 Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* const char *GetAttrib( AstObject *this, const char *attrib, int *status ) - -* Class Membership: -* Frame member function (over-rides the protected astGetAttrib -* method inherited from the Mapping class). - -* Description: -* This function returns a pointer to the value of a specified -* attribute for a Frame, formatted as a character string. - -* Parameters: -* this -* Pointer to the Frame. -* 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: -* - This function uses one-based axis numbering so that it is -* suitable for external (public) use. -* - The returned string pointer may point at memory allocated -* within the Frame, 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 Frame. 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 /* Declare the thread specific global data */ - AstAxis *ax; /* Pointer to Axis */ - AstFrame *pfrm; /* Pointer to primary Frame containing axis */ - AstFrame *this; /* Pointer to the Frame structure */ - AstSystemType system; /* System code */ - char pfrm_attrib[ 100 ]; /* Primary Frame attribute */ - char *axis_attrib; /* Pointer to axis attribute name */ - const char *old_attrib; /* Pointer to supplied attribute name string */ - const char *result; /* Pointer value to return */ - double dval; /* Double attibute value */ - double epoch; /* Epoch attribute value (as MJD) */ - int axis; /* Frame axis number */ - int axis_nc; /* No. characters in axis attribute name */ - int digits; /* Digits attribute value */ - int direction; /* Direction attribute value */ - int free_axis_attrib; /* Should axis_attrib be freed? */ - int has_axis; /* Does attrib name include axis specifier? */ - int len; /* Length of attrib string */ - int match_end; /* MatchEnd attribute value */ - int max_axes; /* MaxAxes attribute value */ - int min_axes; /* MinAxes attribute value */ - int naxes; /* Naxes attribute value */ - int nc; /* No. characters read by astSscanf */ - int oldrep; /* Original error reporting state */ - int paxis; /* Axis index within primary frame */ - int permute; /* Permute attribute value */ - int preserve_axes; /* PreserveAxes attribute value */ - int used; /* Could the setting string be used? */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this_object); - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_object; - -/* Set a flag indicating if the attribute name includes an axis - specifier. */ - has_axis = ( strchr( attrib, '(' ) != NULL ); - -/* A flag indicating that we do not need to free the axis_attrib memory. */ - free_axis_attrib = 0; - -/* Initialise things to avoid compiler warnings. */ - axis_attrib = NULL; - old_attrib = NULL; - -/* Jump back to here if we are trying the same attribute but with an explicit - axis "(1)" added to the end of the name. */ -L1: - -/* Obtain the length of the attrib string. */ - len = strlen( attrib ); - -/* Save the number of axes in the Frame for later use. */ - naxes = astGetNaxes( this ); - -/* 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. */ - -/* Digits. */ -/* ------- */ - if ( !strcmp( attrib, "digits" ) ) { - digits = astGetDigits( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", digits ); - result = getattrib_buff; - } - -/* Digits(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "digits(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - -/* There is no function to obtain the Digits attribute value for an - axis directly, so obtain a pointer to the Axis and use this to - obtain the value. Use the Frame's Digits attribute instead if the - Axis attribute value is not set. */ - (void) astValidateAxis( this, axis - 1, 1, "astGetDigits(axis)" ); - ax = astGetAxis( this, axis - 1 ); - if ( astTestAxisDigits( ax ) ) { - digits = astGetAxisDigits( ax ); - } else { - digits = astGetDigits( this ); - } - ax = astAnnul( ax ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", digits ); - result = getattrib_buff; - } - - -/* Direction(axis). */ -/* ---------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "direction(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - direction = astGetDirection( this, axis - 1 ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", direction ); - result = getattrib_buff; - } - -/* Epoch. */ -/* ------ */ - } else if ( !strcmp( attrib, "epoch" ) ) { - epoch = astGetEpoch( this ); - if ( astOK ) { - -/* Format the Epoch as decimal years. Use a Besselian epoch if it will - be less than 1984.0, otherwise use a Julian epoch. */ - result = astFmtDecimalYr( ( epoch < palEpj2d( 1984.0 ) ) ? - palEpb( epoch ) : palEpj( epoch ), AST__DBL_DIG ); - } - -/* Top(axis). */ -/* ---------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "top(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - dval = astGetTop( this, axis -1 ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%.*g", AST__DBL_DIG, dval ); - result = getattrib_buff; - } - -/* Bottom(axis). */ -/* ---------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "bottom(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - dval = astGetBottom( this, axis -1 ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%.*g", AST__DBL_DIG, dval ); - result = getattrib_buff; - } - -/* Domain. */ -/* ------- */ - } else if ( !strcmp( attrib, "domain" ) ) { - result = astGetDomain( this ); - -/* Format(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "format(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astGetFormat( this, axis - 1 ); - -/* Label(axis). */ -/* ------------ */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "label(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astGetLabel( this, axis - 1 ); - -/* MatchEnd. */ -/* --------- */ - } else if ( !strcmp( attrib, "matchend" ) ) { - match_end = astGetMatchEnd( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", match_end ); - result = getattrib_buff; - } - -/* MaxAxes. */ -/* -------- */ - } else if ( !strcmp( attrib, "maxaxes" ) ) { - max_axes = astGetMaxAxes( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", max_axes ); - result = getattrib_buff; - } - -/* MinAxes. */ -/* -------- */ - } else if ( !strcmp( attrib, "minaxes" ) ) { - min_axes = astGetMinAxes( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", min_axes ); - result = getattrib_buff; - } - -/* Naxes. */ -/* -----_ */ - } else if ( !strcmp( attrib, "naxes" ) ) { - (void) sprintf( getattrib_buff, "%d", naxes ); - result = getattrib_buff; - -/* Permute. */ -/* -------- */ - } else if ( !strcmp( attrib, "permute" ) ) { - permute = astGetPermute( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", permute ); - result = getattrib_buff; - } - -/* PreserveAxes. */ -/* ------------- */ - } else if ( !strcmp( attrib, "preserveaxes" ) ) { - preserve_axes = astGetPreserveAxes( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", preserve_axes ); - result = getattrib_buff; - } - -/* Symbol(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "symbol(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astGetSymbol( this, axis - 1 ); - -/* AlignSystem. */ -/* ------------ */ -/* Obtain the AlignSystem code and convert to a string. */ - } else if ( !strcmp( attrib, "alignsystem" ) ) { - system = astGetAlignSystem( this ); - if ( astOK ) { - result = astSystemString( this, system ); - -/* Report an error if the value was not recognised. */ - if ( !result ) { - astError( AST__SCSIN, - "astGetAttrib(%s): Corrupt %s contains invalid " - "AlignSystem identification code (%d).", status, - astGetClass( this ), astGetClass( this ), (int) system ); - } - } - -/* System. */ -/* ------- */ -/* Obtain the System code and convert to a string. */ - } else if ( !strcmp( attrib, "system" ) ) { - system = astGetSystem( this ); - if ( astOK ) { - result = astSystemString( this, system ); - -/* Report an error if the value was not recognised. */ - if ( !result ) { - astError( AST__SCSIN, - "astGetAttrib(%s): Corrupt %s contains invalid " - "System identification code (%d).", status, - astGetClass( this ), astGetClass( this ), (int) system ); - } - } - -/* Title. */ -/* ------ */ - } else if ( !strcmp( attrib, "title" ) ) { - result = astGetTitle( this ); - -/* Unit(axis). */ -/* ----------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "unit(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astGetUnit( this, axis - 1 ); - -/* NormUnit(axis). */ -/* --------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "normunit(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astGetNormUnit( this, axis - 1 ); - -/* InternalUnit(axis). */ -/* --------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "internalunit(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astGetInternalUnit( this, axis - 1 ); - -/* ObsLat. */ -/* ------- */ - } else if ( !strcmp( attrib, "obslat" ) ) { - dval = astGetObsLat( this ); - if ( astOK ) { - -/* If not already created, create an FK5 J2000 SkyFrame which will be used - for formatting and unformatting ObsLon and ObsLat values. */ - if( !skyframe ) { - astBeginPM; - skyframe = astSkyFrame("system=FK5,equinox=J2000,format(2)=dms.2", status ); - astEndPM; - } - -/* Display absolute value preceded by "N" or "S" as appropriate. */ - if( dval < 0 ) { - (void) sprintf( getattrib_buff, "S%s", astFormat( skyframe, 1, -dval ) ); - } else { - (void) sprintf( getattrib_buff, "N%s", astFormat( skyframe, 1, dval ) ); - } - result = getattrib_buff; - } - -/* ObsLon. */ -/* ------- */ - } else if ( !strcmp( attrib, "obslon" ) ) { - dval = astGetObsLon( this ); - if ( astOK ) { - -/* Put into range +/- PI. */ - dval = palDrange( dval ); - -/* If not already created, create an FK5 J2000 SkyFrame which will be used - for formatting and unformatting ObsLon and ObsLat values. */ - if( !skyframe ) { - astBeginPM; - skyframe = astSkyFrame( "system=FK5,equinox=J2000,format(2)=dms.2", status ); - astEndPM; - } - -/* Display absolute value preceded by "E" or "W" as appropriate. */ - if( dval < 0 ) { - (void) sprintf( getattrib_buff, "W%s", astFormat( skyframe, 1, -dval ) ); - } else { - (void) sprintf( getattrib_buff, "E%s", astFormat( skyframe, 1, dval ) ); - } - result = getattrib_buff; - - } - -/* ObsAlt. */ -/* ------- */ - } else if ( !strcmp( attrib, "obsalt" ) ) { - dval = astGetObsAlt( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%.*g", AST__DBL_DIG, dval ); - result = getattrib_buff; - } - -/* Dtai. */ -/* ---- */ - } else if ( !strcmp( attrib, "dtai" ) ) { - dval = astGetDtai( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%.*g", AST__DBL_DIG, dval ); - result = getattrib_buff; - } - -/* Dut1. */ -/* ---- */ - } else if ( !strcmp( attrib, "dut1" ) ) { - dval = astGetDut1( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%.*g", AST__DBL_DIG, dval ); - result = getattrib_buff; - } - -/* Other axis attributes. */ -/* ---------------------- */ -/* If the attribute was not identified above, but appears to refer to - a Frame axis, then it may refer to an Axis object of a derived type - (which has additional attributes not recognised here). */ - } else if ( !free_axis_attrib && ( nc = 0, - ( 1 == astSscanf( attrib, "%*[^()]%n(%d)%n", - &axis_nc, &axis, &nc ) ) - && ( nc >= len ) ) ) { - -/* Validate the axis index and extract the attribute name. */ - (void) astValidateAxis( this, axis - 1, 1, "astGet" ); - axis_attrib = astString( attrib, axis_nc ); - -/* Obtain a pointer to the Axis object. */ - ax = astGetAxis( this, axis - 1 ); - if( astOK ) { - -/* Assume that we will be able to use the attribute name. */ - used = 1; - -/* Temporarily switch off error reporting so that if the following attempt - to access the axis attribute fails, we can try to interpret the - attribute name as an attribute of the primary Frame containing the - specified axis. Any errors reported in this context will simply be - ignored, in particularly they are not deferred for later delivery. */ - oldrep = astReporting( 0 ); - -/* Use the Axis astGetAttrib method to obtain the result. */ - result = astGetAttrib( ax, axis_attrib ); - -/* If the above call failed with a status of AST__BADAT, indicating that - the attribute name was not recognised, clear the status so that we can - try to interpret the attribute name as an attribute of the primary Frame - containing the specified axis. */ - if( astStatus == AST__BADAT ) { - astClearStatus; - -/* Find the primary Frame containing the specified axis. */ - astPrimaryFrame( this, axis - 1, &pfrm, &paxis ); - -/* Only attempt to use the primary Frame if it is not the same as "this" - - otherwise we could end up in an infinite loop. */ - if( pfrm != this ) { - -/* astPrimaryFrame returns the original - unpermuted - axis index within - the primary Frame. So we need to take into account any axis permutation - which has been applied to the primary Frame when forming the attribute name - to use below. Find the permuted (external) axis index which corresponds to - the internal (unpermuted) axis index "paxis". */ - paxis = astValidateAxis( pfrm, paxis, 0, "astGet" ); - -/* Modify the attribute name to refer to the axis numbering of the - primary frame. */ - sprintf( pfrm_attrib, "%s(%d)", axis_attrib, paxis + 1 ); - -/* Attempt to use the Axis astGetAttrib method to obtain the result. */ - result = astGetAttrib( pfrm, pfrm_attrib ); - -/* If this failed, clear the status and indicate that we have not managed to - use the attribute name. */ - if( !astOK ) { - astClearStatus; - used = 0; - } - - } else { - used = 0; - } - -/* If not found attempt to get the attribute value from the Axis, omitting - the axis index. */ - if( ! used ) { - result = astGetAttrib( pfrm, axis_attrib ); - if( !astOK ) { - astClearStatus; - } else { - used = 1; - } - } - -/* Annul the primary Frame pointer. */ - pfrm = astAnnul( pfrm ); - } - -/* Re-instate the original error reporting state. */ - astReporting( oldrep ); - -/* If we could not use the attribute name, attempt to get the axis - attribute again, this time retaining the error report. This is done - to ensure the user gets an appropriate error message. */ - if( !used ) result = astGetAttrib( ax, axis_attrib ); - } - -/* Annul the Axis pointer and free the memory holding the attribute - name. */ - ax = astAnnul( ax ); - axis_attrib = astFree( axis_attrib ); - -/* Not recognised. */ -/* --------------- */ -/* If the attribute is still not recognised, and the Frame has only 1 axis, - and the attribute name does not already include an axis specifier, try - again after appending "(1)" to the end of the attribute name. */ - } else if( !has_axis && naxes == 1 ) { - -/* Take a copy of the supplied name, allowing 3 extra characters for the - axis specifier "(1)". */ - axis_attrib = astMalloc( len + 4 ); - if( axis_attrib ) memcpy( axis_attrib, attrib, len ); - -/* Indicate we should free the axis_attrib memory. */ - free_axis_attrib = 1; - -/* Add in the axis specifier. */ - strcpy( axis_attrib + len, "(1)" ); - -/* Use the new attribute name instead of the supplied name. */ - old_attrib = attrib; - attrib = axis_attrib; - -/* Indicate the attribute name now has an axis specifier. */ - has_axis = 1; - -/* Jump back to try interpreting the new attribute name. */ - goto L1; - -/* Not recognised. */ -/* --------------- */ -/* If the attribute name is still not recognised, pass it on to the parent - method for further interpretation. First re-instate the original attrib - name string if it was changed above. */ - } else { - if( free_axis_attrib ) { - attrib = old_attrib; - axis_attrib = astFree( axis_attrib ); - } - result = (*parent_getattrib)( this_object, attrib, status ); - } - -/* Return the result. */ - return result; -} - -static AstAxis *GetAxis( AstFrame *this, int axis, int *status ) { -/* -*+ -* Name: -* astGetAxis - -* Purpose: -* Obtain a pointer to a specified Axis from a Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* AstAxis *astGetAxis( AstFrame *this, int axis ) - -* Class Membership: -* Frame method. - -* Description: -* This function returns a pointer to the Axis object associated -* with one of the axes of a Frame. This object describes the -* quantity which is represented along that axis. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The number of the axis (zero-based) for which an Axis pointer is -* required. - -* 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 */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Initialise. */ - result = NULL; - -/* Validate and permute the axis index. */ - axis = astValidateAxis( this, axis, 1, "astGetAxis" ); - -/* If OK, clone the required Axis pointer. */ - if ( astOK ) result = astClone( this->axis[ axis ] ); - -/* Return the result. */ - return result; -} - -static const char *GetDefaultLabel( int axis, int *status ) { -/* -* Name: -* GetDefaultLabel - -* Purpose: -* Return a pointer to a default axis Label string. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* const char *GetDefaultLabel( int axis, int *status ) - -* Class Membership: -* Frame member function - -* Description: -* This function returns a pointer to a string holding a default axis -* Label value. - -* Parameters: -* axis -* Zero based axis index. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* - Pointer to a static null-terminated string containing the attribute -* value. - -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(NULL); - -/* Format the axis index, putting the string in a global buffer. */ - (void) sprintf( label_buff, "Axis %d", axis + 1 ); - -/* Return a pointer to the global buffer. */ - return label_buff; -} - -static const char *GetDefaultSymbol( AstFrame *this, int axis, int *status ) { -/* -* Name: -* GetDefaultSymbol - -* Purpose: -* Return a pointer to a default axis Symbol string. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* const char *GetDefaultSymbol( AstFrame *this, int axis, int *status ) - -* Class Membership: -* Frame member function - -* Description: -* This function returns a pointer to a string holding a default axis -* Symbol value. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* Zero based axis index. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* - Pointer to a static null-terminated string containing the attribute -* value. - -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this); - -/* Note we use "sprintf" once to determine how many characters are - produced by the "%d" format string and then limit the number of - characters used from the Domain string in the second invocation of - "sprintf" so that the total length of the default Symbol string - does not exceed SYMBOL_BUFF_LEN characters. */ - (void) sprintf( symbol_buff, "%.*s%d", - SYMBOL_BUFF_LEN - sprintf( symbol_buff, "%d", axis + 1 ), - astTestDomain( this ) ? astGetDomain( this ) : "x", - axis + 1 ); - -/* Use the AddUnderscores function to replace any white space in the Symbol - string with underscore characters. */ - AddUnderscores( symbol_buff, status ); - -/* Return a pointer to the global buffer. */ - return symbol_buff; -} - -static const char *GetDefaultTitle( AstFrame *this, int *status ) { -/* -* Name: -* GetDefaultTitle - -* Purpose: -* Return a pointer to a default Title string. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* const char *GetDefaultTitle( AstFrame *this, int *status ) - -* Class Membership: -* Frame member function - -* Description: -* This function returns a pointer to a string holding a default Title value. - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* - Pointer to a static null-terminated string containing the attribute -* value. - -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this); - -/* Create the Title value and put it in the global buffer. */ - (void) sprintf( title_buff, "%d-d coordinate system", astGetNaxes( this ) ); - -/* Return a pointer to the global buffer. */ - return title_buff; -} - -static int GetFrameFlags( AstFrame *this, int *status ){ -/* -*+ -* Name: -* astGetFrameFlags - -* Purpose: -* Return the bit mask of flags associated with a Frame. - -* Type: -* Protected function. - -* Synopsis: -* #include "frame.h" -* int *astGetFrameFlags( astFrame *this ) - -* Class Membership: -* Frame virtual function. - -* Description: -* This function returns a bit mask holding the current set of flags -* associated with a Frame. See astSetFrameFlags for details of these -* flags. - -* Parameters: -* this -* The Frame. - -* Returned Value: -* The bit mask. - -* Notes: -* - Zero is 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 0; - -/* Return the result. */ - return this->flags; -} - -static int GetIsLinear( AstMapping *this_mapping, int *status ){ -/* -* Name: -* GetIsLinear - -* Purpose: -* Return the value of the IsLinear attribute for a Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "mapping.h" -* void GetIsLinear( AstMapping *this, int *status ) - -* Class Membership: -* Frame member function (over-rides the protected astGetIsLinear -* method inherited from the Mapping class). - -* Description: -* This function returns the value of the IsLinear attribute for a -* Frame, which is always one because a Frame is treated like a UnitMap. - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. -*/ - return 1; -} - -static int GetIsSimple( AstMapping *this_mapping, int *status ){ -/* -* Name: -* GetIsSimple - -* Purpose: -* Return the value of the IsSimple attribute for a Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "mapping.h" -* void GetIsSimple( AstMapping *this, int *status ) - -* Class Membership: -* Frame member function (over-rides the protected astGetIsSimple -* method inherited from the Mapping class). - -* Description: -* This function returns the value of the IsSimple attribute for a -* Frame, which is always zero because Frames are not immutable (unlike -* non-Frame Mappings). - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. -*/ - return 0; -} - -static int GetNaxes( AstFrame *this, int *status ) { -/* -*+ -* Name: -* astGetNaxes - -* Purpose: -* Determine how many axes a Frame has. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astGetNaxes( AstFrame *this ) - -* Class Membership: -* Frame method. - -* Description: -* This function returns the number of axes for a Frame. - -* Parameters: -* this -* Pointer to the Frame. - -* Returned Value: -* The number of Frame axes. - -* 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. -*- -*/ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Return the number of Frame axes. */ - return this->naxes; -} - -static int GetNin( AstMapping *this_mapping, int *status ) { -/* -* Name: -* GetNin - -* Purpose: -* Get the number of input coordinates for a Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int GetNin( AstMapping *this, int *status ) - -* Class Membership: -* Frame member function (over-rides the astGetNin method inherited -* from the Mapping class). - -* Description: -* This function returns the number of input coordinate values -* required per point by a Frame, when used as a Mapping (i.e. the -* number of dimensions of the space in which input points reside). - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Number of coordinate values required. - -* 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 *this; /* Pointer to Frame structure */ - int result; /* Result value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_mapping; - -/* Return the number of Frame axes. */ - result = astGetNaxes( this ); - -/* Return the result. */ - return result; -} - -static int GetNout( AstMapping *this_mapping, int *status ) { -/* -* Name: -* GetNout - -* Purpose: -* Get the number of output coordinates for a Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int GetNout( AstMapping *this, int *status ) - -* Class Membership: -* Frame member function (over-rides the astGetNout method -* inherited from the Mapping class). - -* Description: -* This function returns the number of output coordinate values -* generated per point by a Frame, when used as a Mapping (i.e. the -* number of dimensions of the space in which output points -* reside). - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Number of coordinate values generated. - -* 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 *this; /* Pointer to Frame structure */ - int result; /* Result value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_mapping; - -/* Return the number of Frame axes. */ - result = astGetNaxes( this ); - -/* 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 "frame.h" -* int GetObjSize( AstObject *this, int *status ) - -* Class Membership: -* Frame member function (over-rides the astGetObjSize protected -* method inherited from the parent class). - -* Description: -* This function returns the in-memory size of the supplied Frame, -* in bytes. - -* Parameters: -* this -* Pointer to the Frame. -* 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: */ - AstFrame *this; /* Pointer to Frame structure */ - int axis; /* Axis index */ - int result; /* Result value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointers to the FrameSet structure. */ - this = (AstFrame *) this_object; - -/* Invoke the GetObjSize method inherited from the parent class, and then - add on any components of the class structure defined by this class - which are stored in dynamically allocated memory. */ - result = (*parent_getobjsize)( this_object, status ); - result += astGetObjSize( this->variants ); - result += astTSizeOf( this->domain ); - result += astTSizeOf( this->title ); - result += astTSizeOf( this->axis ); - result += astTSizeOf( this->perm ); - - for ( axis = 0; axis < this->naxes; axis++ ) { - result += astGetObjSize( this->axis[ axis ] ); - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result, */ - return result; -} - -static const int *GetPerm( AstFrame *this, int *status ) { -/* -*+ -* Name: -* astGetPerm - -* Purpose: -* Access the axis permutation array for a Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* const int *astGetPerm( AstFrame *this ) - -* Class Membership: -* Frame method. - -* Description: -* This function returns a pointer to the axis permutation array -* for a Frame. 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 Frame. - -* Returned Value: -* Pointer to the 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 Frame has -* zero axes, this pointer will be NULL. - -* Notes: -* - This protected method is provided to assist class -* implementations which need to implement axis-dependent -* extensions to Frame methods, and which therefore need to know -* how a Frames's external axis index is converted for internal -* use. -* - 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. -*- -*/ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Return a pointer to the axis permutation array. */ - return this->perm; -} - -static AstFrameSet *GetFrameVariants( AstFrame *this, int *status ){ -/* -*+ -* Name: -* astGetFrameVariants - -* Purpose: -* Returns the FrameSet holding the available Frame variants. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* AstFrameSet *astGetFrameVariants( AstFrame *this ) - -* Class Membership: -* Frame method. - -* Description: -* This function returns a pointer to any FrameSet previously stored -* in the Frame using method astSetVariants. - -* Parameters: -* this -* Pointer to the Frame. - -* Returned Value: -* astGetFrameVariants -* A pointer to the FrameSet. It should be annulled using astAnnul -* when no longer needed. NULL will be returned if no FrameSet is -* stored in the Frame. - -* Notes: -* - A NULL 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: */ - AstFrameSet *result; - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get a clone of any FrameSet pointer. */ - if( this->variants ) result = astClone( this->variants ); - -/* Return the result. */ - return result; -} - -void astInitFrameVtab_( AstFrameVtab *vtab, const char *name, int *status ) { -/* -*+ -* Name: -* astInitFrameVtab - -* Purpose: -* Initialise a virtual function table for a Frame. - -* Type: -* Protected function. - -* Synopsis: -* #include "frame.h" -* void astInitFrameVtab( AstFrameVtab *vtab, const char *name ) - -* Class Membership: -* Frame vtab initialiser. - -* Description: -* This function initialises the component of a virtual function -* table which is used by the Frame 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 */ - AstObjectVtab *object; /* Pointer to Object component of Vtab */ - AstMappingVtab *mapping; /* Pointer to Mapping 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. */ - astInitMappingVtab( (AstMappingVtab *) vtab, name ); - -/* Store a unique "magic" value in the virtual function table. This - will be used (by astIsAFrame ) 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 = &(((AstMappingVtab *) vtab)->id); - -/* Initialise member function pointers. */ -/* ------------------------------------ */ -/* Store pointers to the member functions (implemented here) that provide - virtual methods for this class. */ - vtab->Abbrev = Abbrev; - vtab->CheckPerm = CheckPerm; - vtab->ClearDigits = ClearDigits; - vtab->ClearDirection = ClearDirection; - vtab->ClearDomain = ClearDomain; - vtab->ClearFormat = ClearFormat; - vtab->ClearLabel = ClearLabel; - vtab->ClearMatchEnd = ClearMatchEnd; - vtab->ClearMaxAxes = ClearMaxAxes; - vtab->ClearMinAxes = ClearMinAxes; - vtab->ClearPermute = ClearPermute; - vtab->ClearPreserveAxes = ClearPreserveAxes; - vtab->ClearSymbol = ClearSymbol; - vtab->ClearTitle = ClearTitle; - vtab->ClearUnit = ClearUnit; - vtab->Convert = Convert; - vtab->ConvertX = ConvertX; - vtab->Angle = Angle; - vtab->Distance = Distance; - vtab->Fields = Fields; - vtab->FindFrame = FindFrame; - vtab->MatchAxes = MatchAxes; - vtab->MatchAxesX = MatchAxesX; - vtab->Format = Format; - vtab->Centre = Centre; - vtab->Gap = Gap; - vtab->GetAxis = GetAxis; - vtab->GetDigits = GetDigits; - vtab->GetDirection = GetDirection; - vtab->GetDomain = GetDomain; - vtab->GetFormat = GetFormat; - vtab->GetLabel = GetLabel; - vtab->GetMatchEnd = GetMatchEnd; - vtab->GetMaxAxes = GetMaxAxes; - vtab->GetMinAxes = GetMinAxes; - vtab->GetNaxes = GetNaxes; - vtab->GetPerm = GetPerm; - vtab->GetPermute = GetPermute; - vtab->GetPreserveAxes = GetPreserveAxes; - vtab->GetSymbol = GetSymbol; - vtab->GetTitle = GetTitle; - vtab->GetUnit = GetUnit; - vtab->GetInternalUnit = GetInternalUnit; - vtab->GetNormUnit = GetNormUnit; - vtab->Intersect = Intersect; - vtab->IsUnitFrame = IsUnitFrame; - vtab->Match = Match; - vtab->Norm = Norm; - vtab->NormBox = NormBox; - vtab->AxDistance = AxDistance; - vtab->AxNorm = AxNorm; - vtab->AxOffset = AxOffset; - vtab->AxIn = AxIn; - vtab->AxAngle = AxAngle; - vtab->FrameGrid = FrameGrid; - vtab->Offset = Offset; - vtab->Offset2 = Offset2; - vtab->Resolve = Resolve; - vtab->ResolvePoints = ResolvePoints; - vtab->LineDef = LineDef; - vtab->LineContains = LineContains; - vtab->LineCrossing = LineCrossing; - vtab->LineOffset = LineOffset; - vtab->Overlay = Overlay; - vtab->PermAxes = PermAxes; - vtab->PickAxes = PickAxes; - vtab->PrimaryFrame = PrimaryFrame; - vtab->SetAxis = SetAxis; - vtab->SetDigits = SetDigits; - vtab->SetDirection = SetDirection; - vtab->SetDomain = SetDomain; - vtab->SetFormat = SetFormat; - vtab->SetLabel = SetLabel; - vtab->SetMatchEnd = SetMatchEnd; - vtab->SetMaxAxes = SetMaxAxes; - vtab->SetMinAxes = SetMinAxes; - vtab->SetPermute = SetPermute; - vtab->SetPreserveAxes = SetPreserveAxes; - vtab->SetSymbol = SetSymbol; - vtab->SetTitle = SetTitle; - vtab->SetUnit = SetUnit; - vtab->SubFrame = SubFrame; - vtab->TestDigits = TestDigits; - vtab->TestDirection = TestDirection; - vtab->TestDomain = TestDomain; - vtab->TestFormat = TestFormat; - vtab->TestLabel = TestLabel; - vtab->TestMatchEnd = TestMatchEnd; - vtab->TestMaxAxes = TestMaxAxes; - vtab->TestMinAxes = TestMinAxes; - vtab->TestPermute = TestPermute; - vtab->TestPreserveAxes = TestPreserveAxes; - vtab->TestSymbol = TestSymbol; - vtab->TestTitle = TestTitle; - vtab->TestUnit = TestUnit; - vtab->Unformat = Unformat; - vtab->ValidateAxis = ValidateAxis; - vtab->ValidateAxisSelection = ValidateAxisSelection; - vtab->ValidateSystem = ValidateSystem; - vtab->SystemString = SystemString; - vtab->SystemCode = SystemCode; - - vtab->GetFrameFlags = GetFrameFlags; - vtab->SetFrameFlags = SetFrameFlags; - - vtab->TestActiveUnit = TestActiveUnit; - vtab->GetActiveUnit = GetActiveUnit; - vtab->SetActiveUnit = SetActiveUnit; - - vtab->GetFrameVariants = GetFrameVariants; - vtab->SetFrameVariants = SetFrameVariants; - - vtab->ClearSystem = ClearSystem; - vtab->GetSystem = GetSystem; - vtab->SetSystem = SetSystem; - vtab->TestSystem = TestSystem; - - vtab->ClearAlignSystem = ClearAlignSystem; - vtab->GetAlignSystem = GetAlignSystem; - vtab->SetAlignSystem = SetAlignSystem; - vtab->TestAlignSystem = TestAlignSystem; - - vtab->ClearTop = ClearTop; - vtab->GetTop = GetTop; - vtab->SetTop = SetTop; - vtab->TestTop = TestTop; - - vtab->ClearBottom = ClearBottom; - vtab->GetBottom = GetBottom; - vtab->SetBottom = SetBottom; - vtab->TestBottom = TestBottom; - - vtab->ClearEpoch = ClearEpoch; - vtab->GetEpoch = GetEpoch; - vtab->SetEpoch = SetEpoch; - vtab->TestEpoch = TestEpoch; - - vtab->ClearObsLat = ClearObsLat; - vtab->TestObsLat = TestObsLat; - vtab->GetObsLat = GetObsLat; - vtab->SetObsLat = SetObsLat; - - vtab->ClearObsLon = ClearObsLon; - vtab->TestObsLon = TestObsLon; - vtab->GetObsLon = GetObsLon; - vtab->SetObsLon = SetObsLon; - - vtab->ClearObsAlt = ClearObsAlt; - vtab->TestObsAlt = TestObsAlt; - vtab->GetObsAlt = GetObsAlt; - vtab->SetObsAlt = SetObsAlt; - - vtab->ClearDtai = ClearDtai; - vtab->GetDtai = GetDtai; - vtab->SetDtai = SetDtai; - vtab->TestDtai = TestDtai; - - vtab->ClearDut1 = ClearDut1; - vtab->GetDut1 = GetDut1; - vtab->SetDut1 = SetDut1; - vtab->TestDut1 = TestDut1; - -/* Save the inherited pointers to methods that will be extended, and - replace them with pointers to the new member functions. */ - object = (AstObjectVtab *) vtab; - - parent_getobjsize = object->GetObjSize; - object->GetObjSize = GetObjSize; - parent_clearattrib = object->ClearAttrib; - object->ClearAttrib = ClearAttrib; - parent_getattrib = object->GetAttrib; - object->GetAttrib = GetAttrib; - parent_setattrib = object->SetAttrib; - object->SetAttrib = SetAttrib; - parent_testattrib = object->TestAttrib; - object->TestAttrib = TestAttrib; - - parent_cleanattribs = object->CleanAttribs; - object->CleanAttribs = CleanAttribs; - -#if defined(THREAD_SAFE) - parent_managelock = object->ManageLock; - object->ManageLock = ManageLock; -#endif - -/* Store replacement pointers for methods which will be over-ridden by - new member functions implemented here. */ - mapping = (AstMappingVtab *) vtab; - - object->Equal = Equal; - mapping->GetIsLinear = GetIsLinear; - mapping->GetIsSimple = GetIsSimple; - mapping->GetNin = GetNin; - mapping->GetNout = GetNout; - mapping->ReportPoints = ReportPoints; - mapping->Transform = Transform; - mapping->MapSplit = MapSplit; - mapping->DoNotSimplify = DoNotSimplify; - -/* Declare the copy constructor, destructor and class dump - function. */ - astSetCopy( vtab, Copy ); - astSetDelete( vtab, Delete ); - astSetDump( vtab, Dump, "Frame", "Coordinate system description" ); - -/* 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, const double a1[2], - const double a2[2], const double b1[2], - const double b2[2], double cross[2], - int *status ) { -/* -*++ -* Name: -c astIntersect -f AST_INTERSECT - -* Purpose: -* Find the point of intersection between two geodesic curves. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c void astIntersect( AstFrame *this, const double a1[2], -c const double a2[2], const double b1[2], -c const double b2[2], double cross[2] ) -f CALL AST_INTERSECT( THIS, A1, A2, B1, B2, CROSS, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function -f This routine -* finds the coordinate values at the point of intersection between -* two geodesic curves. Each curve is specified by two points on -* the curve. It can only be used with 2-dimensional Frames. -* -* For example, in a basic Frame, it will find the point of -* intersection between two straight lines. But for a SkyFrame it -* will find an intersection of two great circles. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c a1 -f A1( 2 ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This should contain the coordinates of the -* first point on the first geodesic curve. -c a2 -f A2( 2 ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This should contain the coordinates of a -* second point on the first geodesic curve. It should not be -* co-incident with the first point. -c b1 -f B1( 2 ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This should contain the coordinates of the -* first point on the second geodesic curve. -c b2 -f B2( 2 ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This should contain the coordinates of a -* second point on the second geodesic curve. It should not be -* co-incident with the first point. -c cross -f CROSS( 2 ) = DOUBLE PRECISION (Returned) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* in which the coordinates of the required intersection will -* be returned. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -* - 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 -c "a1". -f A1. -* - This function will return "bad" coordinate values (AST__BAD) -* if any of the input coordinates has this value, or if the two -* points defining either geodesic are co-incident, or if the two -* curves do not intersect. -c - The geodesic curve used by this function is the path of -f - The geodesic curve used by this routine is the path of -* shortest distance between two points, as defined by the -c astDistance function. -f AST_DISTANCE function. -* - An error will be reported if the Frame is not 2-dimensional. -*-- -*/ - -/* Local Variables: */ - double ca; /* Y axis intercept of line a */ - double cb; /* Y axis intercept of line b */ - double dxa; /* X range spanned by line a */ - double dxb; /* X range spanned by line b */ - double ma; /* Gradient of line a */ - double mb; /* Gradient of line b */ - int naxes; /* Number of Frame axes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Initialize bad values. */ - cross[ 0 ] = AST__BAD; - cross[ 1 ] = AST__BAD; - -/* Determine the number of Frame axes. */ - naxes = astGetNaxes( this ); - -/* Report an error if the Frame is not 2 dimensional. */ - if( naxes != 2 && astOK ) { - astError( AST__NAXIN, "astIntersect(%s): Invalid number of Frame axes (%d)." - " astIntersect can only be used with 2 dimensonal Frames.", status, - astGetClass( this ), naxes ); - } - -/* Check that all supplied values are OK. */ - if ( ( a1[ 0 ] != AST__BAD ) && ( a1[ 1 ] != AST__BAD ) && - ( a2[ 0 ] != AST__BAD ) && ( a2[ 1 ] != AST__BAD ) && - ( b1[ 0 ] != AST__BAD ) && ( b1[ 1 ] != AST__BAD ) && - ( b2[ 0 ] != AST__BAD ) && ( b2[ 1 ] != AST__BAD ) ) { - -/* Find the x increments spanned by the two lines. */ - -/* Check the first line is not vertical. */ - dxa = a2[ 0 ] - a1[ 0 ]; - dxb = b2[ 0 ] - b1[ 0 ]; - if( dxa != 0.0 ) { - -/* Find the gradient and Y axis intercept of the first line. */ - ma = ( a2[ 1 ] - a1[ 1 ] )/dxa; - ca = a1[ 1 ] - a1[ 0 ]*ma; - -/* Check the second line is not vertical. */ - if( dxb != 0.0 ) { - -/* Find the gradient and Y axis intercept of the second line. */ - mb = ( b2[ 1 ] - b1[ 1 ] )/dxb; - cb = b1[ 1 ] - b1[ 0 ]*mb; - -/* Check the lines are not parallel. */ - if( ma != mb ) { - -/* Find the intersection of the two lines. */ - cross[ 0 ] = ( cb -ca )/( ma - mb ); - cross[ 1 ] = ( ( ma + mb )*cross[ 0 ] + ca + cb )/2; - } - -/* If the second line is vertical but the first is not. */ - } else if( b1[ 1 ] != b2[ 1 ] ){ - cross[ 0 ] = b1[ 0 ]; - cross[ 1 ] = ma*b1[ 0 ] + ca; - } - -/* First line is vertical but second is not. */ - } else if( dxb != 0.0 && a1[ 1 ] != a2[ 1 ] ){ - -/* Find the gradient and Y axis intercept of the second line. */ - mb = ( b2[ 1 ] - b1[ 1 ] )/dxb; - cb = b1[ 1 ] - b1[ 0 ]*mb; - -/* Find the intercection. */ - cross[ 0 ] = a1[ 0 ]; - cross[ 1 ] = mb*a1[ 0 ] + cb; - } - } -} - -static int IsUnitFrame( AstFrame *this, int *status ){ -/* -*+ -* Name: -* astIsUnitFrame - -* Purpose: -* Is this Frame equivalent to a UnitMap? - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astIsUnitFrame( AstFrame *this ) - -* Class Membership: -* Frame method. - -* 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. - -* Returned Value: -* A non-zero value is returned if the supplied Frame is equivalent to -* a UnitMap when treated as a Mapping. - -*- -*/ - -/* Check the local error status. */ - if( !astOK ) return 0; - -/* The base Frame class is always equivalent to a UnitMap. */ - return 1; -} - -static int LineContains( AstFrame *this, AstLineDef *l, int def, double *point, int *status ) { -/* -*+ -* Name: -* astLineContains - -* Purpose: -* Determine if a line contains a point. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astLineContains( AstFrame *this, AstLineDef *l, int def, double *point ) - -* Class Membership: -* Frame method. - -* 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"). - -* 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: */ - int result; - double dx, dy, p; - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Check that the line refers to the supplied Frame. */ - if( l->frame != this ) { - astError( AST__INTER, "astLineContains(%s): The supplied line does " - "not relate to the supplied %s (AST internal programming " - "error).", status, astGetClass( this ), astGetClass( this ) ); - -/* If the point is good, find the offsets from the start of the line. */ - } else if( point[ 0 ] != AST__BAD && point[ 1 ] != AST__BAD ) { - dx = point[ 0 ] - l->start[ 0 ]; - dy = point[ 1 ] - l->start[ 1 ]; - -/* Check the nearest point on the line is between the start and end. - Exclude the end point. */ - p = dx*l->dir[ 0 ] + dy*l->dir[ 1 ]; - if( p >= 0.0 && p < l->length ) { - -/* Check the distance from the point to the nearest point on the line is not - further than 1.0E-7 of the length of the line. */ - if( fabs( dx*l->q[ 0 ] + dy*l->q[ 1 ] ) <= 1.0E-7*l->length ) { - result = 1; - } - } - } - -/* Return zero if an error occurred. */ - if( !astOK ) result = 0; - -/* Return a pointer to the output structure. */ - return result; -} - -static int LineCrossing( AstFrame *this, AstLineDef *l1, AstLineDef *l2, - double **cross, int *status ) { -/* -*+ -* Name: -* astLineCrossing - -* Purpose: -* Determine if two lines cross. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astLineCrossing( AstFrame *this, AstLineDef *l1, AstLineDef *l2, -* double **cross ) - -* Class Membership: -* Frame method. - -* 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. - -* Returned Value: -* A non-zero value is returned if the lines cross at a point which is -* within the [start,end) segment of the lines that are flagged as -* finite (if a line is marked as infinite any crossing is assumed to -* be within the bounds of the line). If the crossing point is outside -* this segment on either (inifinte) 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: */ - double *crossing; /* Returned array */ - double den; /* Denominator */ - double dx; /* Offset in start X values */ - double dy; /* Offset in start Y values */ - double t1; /* Distance from start of line 1 to crossing */ - double t2; /* Distance from start of line 2 to crossing */ - int result; /* Returned value */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Initialise. */ - result = 0; - crossing = astMalloc( sizeof(double)*2 ); - -/* Check that both lines refer to the supplied Frame. */ - if( l1->frame != this ) { - astError( AST__INTER, "astLineCrossing(%s): First supplied line does " - "not relate to the supplied %s (AST internal programming " - "error).", status, astGetClass( this ), astGetClass( this ) ); - - } else if( l2->frame != this ) { - astError( AST__INTER, "astLineCrossing(%s): Second supplied line does " - "not relate to the supplied %s (AST internal programming " - "error).", status, astGetClass( this ), astGetClass( this ) ); - - } else if( crossing ){ - -/* Each of the lines can be represented as "p = start + t.v" where start is - the start position, v is the unit vector pointing from start to end, - and t is the scalar distance from the start position. So to find the - intersection put "start1 + t1.v1 = start2 + t2.v2" and solve for t1 - and t2. */ - den = (l1->dir[ 0 ])*(l2->dir[ 1 ]) - (l2->dir[ 0 ])*(l1->dir[ 1 ]); - if( den != 0.0 ) { - dx = l2->start[ 0 ] - l1->start[ 0 ]; - dy = l2->start[ 1 ] - l1->start[ 1 ]; - t1 = ( l2->dir[ 1 ]*dx - l2->dir[ 0 ]*dy )/den; - t2 = ( l1->dir[ 1 ]*dx - l1->dir[ 0 ]*dy )/den; - -/* Store the crossing point, using the smaller t value to redue error. */ - if( fabs( t1 ) < fabs( t2 ) ) { - crossing[ 0 ] = l1->start[ 0 ] + t1*l1->dir[ 0 ]; - crossing[ 1 ] = l1->start[ 1 ] + t1*l1->dir[ 1 ]; - } else { - crossing[ 0 ] = l2->start[ 0 ] + t2*l2->dir[ 0 ]; - crossing[ 1 ] = l2->start[ 1 ] + t2*l2->dir[ 1 ]; - } - -/* See if the intersection is within the length of both lines (excluding - the end points). If a line is flagged as infinite, set the "t" parameter - to zero to make it look like the crossing is within the line. */ - if( l1->infinite ) t1 = 0.0; - if( l2->infinite ) t2 = 0.0; - - if( t1 >= 0.0 && t1 < l1->length && - t2 >= 0.0 && t2 < l2->length ) result = 1; - - } else { - crossing[ 0 ] = AST__BAD; - crossing[ 1 ] = AST__BAD; - } - } - -/* Return zero if an error occurred. */ - if( !astOK ) { - crossing = astFree( crossing ); - result = 0; - } - -/* Return the crossing pointer. */ - if( cross ) { - *cross = crossing; - } else if( crossing ){ - crossing = astFree( crossing ); - } - -/* Return a pointer to the output structure. */ - return result; -} - -static AstLineDef *LineDef( AstFrame *this, const double start[2], - const double end[2], int *status ) { -/* -*+ -* Name: -* astLineDef - -* Purpose: -* Creates a structure describing a line segment in a 2D Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* AstLineDef *astLineDef( AstFrame *this, const double start[2], -* const double end[2] ) - -* Class Membership: -* Frame method. - -* 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. - -* 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: */ - AstLineDef *result; /* Pointer to output structure */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Check the Frame has 2 axes. */ - if( astGetNaxes( this ) != 2 ) { - astError( AST__INTER, "astLineDef(%s): The supplied %s is not 2 " - "dimensional (internal AST proramming error).", status, - astGetClass( this ), astGetClass( this ) ); - } - -/* Check the axis values are good */ - if( start[ 0 ] != AST__BAD && start[ 1 ] != AST__BAD && - end[ 0 ] != AST__BAD && end[ 1 ] != AST__BAD ) { - -/* Allocate memory for the returned structure. */ - result = astMalloc( sizeof( AstLineDef ) ); - if( result ) { - -/* Store the supplied axis values in the returned structure. */ - result->start[ 0 ] = start[ 0 ]; - result->start[ 1 ] = start[ 1 ]; - result->end[ 0 ] = end[ 0 ]; - result->end[ 1 ] = end[ 1 ]; - -/* Store the length of the line segment. */ - result->length = astDistance( this, start, end ); - -/* Store a unit vector pointing from the start to the end. */ - if( result->length > 0.0 ) { - result->dir[ 0 ] = ( end[ 0 ] - start[ 0 ] )/result->length; - result->dir[ 1 ] = ( end[ 1 ] - start[ 1 ] )/result->length; - } else { - result->dir[ 0 ] = 1.0; - result->dir[ 1 ] = 0.0; - } - -/* Store a unit vector perpendicular to the line, such that the vector - points to the left, as vewied from the observer, when moving from the - start to the end of the line. */ - result->q[ 0 ] = -result->dir[ 1 ]; - result->q[ 1 ] = result->dir[ 0 ]; - -/* Store a pointer to the defining Frame. */ - result->frame = this; - -/* Indicate that the line is considered to be terminated at the start and - end points. */ - result->infinite = 0; - } - } - -/* Free the returned pointer if an error occurred. */ - if( !astOK ) result = astFree( result ); - -/* Return a pointer to the output structure. */ - return result; -} - -static void LineOffset( AstFrame *this, AstLineDef *line, double par, - double prp, double point[2], int *status ){ -/* -*+ -* Name: -* astLineOffset - -* Purpose: -* Find a position close to a line. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void LineOffset( AstFrame *this, AstLineDef *line, double par, -* double prp, double point[2] ) - -* Class Membership: -* Frame method. - -* 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. - -* 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". -*- -*/ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Check that the line refers to the supplied Frame. */ - if( line->frame != this ) { - astError( AST__INTER, "astLineOffset(%s): The supplied line does " - "not relate to the supplied %s (AST internal programming " - "error).", status, astGetClass( this ), astGetClass( this ) ); - -/* This implementation uses simple flat geometry. */ - } else { - point[ 0 ] = line->start[ 0 ] + par*line->dir[ 0 ] + prp*line->q[ 0 ]; - point[ 1 ] = line->start[ 1 ] + par*line->dir[ 1 ] + prp*line->q[ 1 ]; - } -} - -#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: -* CmpMap 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: */ - AstFrame *this; /* Pointer to Frame structure */ - int i; /* Loop count */ - 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 Frame structure. */ - this = (AstFrame *) 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. */ - for( i = 0; i < this->naxes; i++ ) { - if( !result ) result = astManageLock( this->axis[ i ], mode, extra, - fail ); - } - if( this->variants && !result ) result = astManageLock( this->variants, mode, - extra, fail ); - - return result; - -} -#endif - -static int *MapSplit( AstMapping *this_map, int nin, const int *in, AstMapping **map, int *status ){ -/* -* Name: -* MapSplit - -* Purpose: -* Create a Mapping representing a subset of the inputs of an existing -* Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) - -* Class Membership: -* Frame method (over-rides the protected astMapSplit method -* inherited from the Mapping class). - -* Description: -* This function creates a new Mapping by picking specified inputs from -* an existing Frame. This is only possible if the specified inputs -* correspond to some subset of the Frame outputs. That is, there -* must exist a subset of the Frame outputs for which each output -* depends only on the selected Frame inputs, and not on any of the -* inputs which have not been selected. If this condition is not met -* by the supplied Frame, then a NULL Mapping is returned. - -* Parameters: -* this -* Pointer to the Frame to be split (the Frame is not actually -* modified by this function). -* nin -* The number of inputs to pick from "this". -* in -* Pointer to an array of indices (zero based) for the inputs which -* are to be picked. This array should have "nin" elements. If "Nin" -* is the number of inputs of the supplied Frame, then each element -* should have a value in the range zero to Nin-1. -* map -* Address of a location at which to return a pointer to the new -* Mapping. This Mapping will have "nin" inputs (the number of -* outputs may be different to "nin"). A NULL pointer will be -* returned if the supplied Frame has no subset of outputs which -* depend only on the selected inputs. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A pointer to a dynamically allocated array of ints. The number of -* elements in this array will equal the number of outputs for the -* returned Mapping. Each element will hold the index of the -* corresponding output in the supplied Frame. The array should be -* freed using astFree when no longer needed. A NULL pointer will -* be returned if no output Mapping can be created. - -* Notes: -* - If this function is invoked with the global error status set, -* or if it should fail for any reason, then NULL values will be -* returned as the function value and for the "map" pointer. -*/ - -/* Local Variables: */ - int *result; /* Returned pointer */ - -/* Initialise */ - result = NULL; - *map = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Pick the selected axes from the Frame. */ - *map = (AstMapping *) astPickAxes( (AstFrame *) this_map, nin, in, NULL ); - -/* Return a copy of the supplied axis array.*/ - result = astStore( NULL, in, sizeof( int )*(size_t) nin ); - -/* Free returned resources if an error has occurred. */ - if( !astOK ) { - result = astFree( result ); - *map = astAnnul( *map ); - } - -/* Return the list of output indices. */ - return result; -} - -static int Match( AstFrame *template, AstFrame *target, int matchsub, - int **template_axes, int **target_axes, - AstMapping **map, AstFrame **result, int *status ) { -/* -*+ -* Name: -* astMatch - -* Purpose: -* Determine if conversion is possible between two coordinate systems. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astMatch( AstFrame *template, AstFrame *target, int matchsub, -* int **template_axes, int **target_axes, -* AstMapping **map, AstFrame **result ) - -* Class Membership: -* Frame method. - -* Description: -* This function matches a "template" frame 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 "target" -* coordinate system. 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 Frame. This 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 (i.e. if the -* target is of a more specialised class than the template). In -* this latter case, the target is cast down to the class of the -* template. NOTE, this argument is handled by the global method -* wrapper function "astMatch_", rather than by the class-specific -* implementations of this method. -* 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 (zero-based) index of the -* template Frame axis from which it is derived. If it is not -* derived from any template frame 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 (zero-based) 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 and the template -* Frames. 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. - -* 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: -* - By default, the "result" frame will have its number of axes -* and axis order determined by the "template" Frame. However, if -* the PreserveAxes attribute of the template frame is non-zero, -* then the axis count and axis order of the "target" frame will be -* used instead. -* - The template_axes and target_axes arrays are provided so that -* if the caller needs to permute the target and/or template axes -* before invoking this function, it is possible to deduce how the -* result axes should be permuted so as to correspond with the -* original template/target axis order. -* - For result axes that do not correspond with a template and/or -* target axis (where a value of -1 is returned in the -* template_axes and/or target_axes arrays), the caller has no -* clear way of knowing where these axes should appear in any -* permuted order. In this case, the relative position of these -* axes within the result Frame (with respect to axes that do have -* template/target axis associations) will be used to convey this -* information. Such axes should be taken to be associated either -* with the next preceding or following axis (depending on the -* AST__MATCHEND flag of the template frame) which does have an -* association. -* - If the result Frame has zero axes, then NULL pointer values -* will be returned for *template_axes and *target_axes. -* - 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. -*- - -* Implementation Notes: -* This implementation addresses the matching of a Frame class -* object to other types of Frames (i.e. the target may be from a -* derived class). A Frame will match any other type of Frame with -* an acceptable number of axes but will not distinguish axis order -* (i.e. it will match the axes in whatever order they are -* given). If the template Frame has a value set for its Domain -* attribute, then it will only match another Frame with the same -* Domain. -*/ - -/* Local Variables: */ - char *template_domain; /* Pointer to copy of template domain */ - const char *ptr; /* Pointer to domain string */ - const char *target_domain; /* Pointer to target domain string */ - int match; /* Template matches target? */ - int match_end; /* Match final axes of target? */ - int max_axes; /* Maximum acceptable number of axes */ - int min_axes; /* Minimum acceptable nu,ber of axes */ - int preserve_axes; /* Preserve target axes? */ - int result_axis; /* Loop counter for result axes */ - int result_naxes; /* Number of result axes */ - int target_naxes; /* Number of target axes */ - int template_naxes; /* Number of template axes */ - -/* 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; - -/* The first requirement for a match is that the target object is a Frame. This - is already known to be true, as it forms part of the argument validation - for this function. */ - -/* The second requirement is that the number of target axes is acceptable. - Obtain the number of target axes and the minimum and maximum number of axes - that the template will match. */ - target_naxes = astGetNaxes( target ); - min_axes = astGetMinAxes( template ); - max_axes = astGetMaxAxes( template ); - -/* Test if the number of target axes is acceptable. */ - if ( astOK ) { - match = ( ( target_naxes >= min_axes ) && ( target_naxes <= max_axes ) ); - } - -/* The third requirement is that if the template has its Domain - attribute defined, then the target must also have the same Domain - (although it need not be set - the default will do). First check if - the template has a domain. */ - if ( astOK && match ) { - if ( astTestDomain( template ) ) { - -/* Obtain a pointer to the template domain. Then allocate memory and - make a copy of it (this is necessary as we will next inquire the - domain of the target and may over-write the buffer holding the - template's domain). */ - ptr = astGetDomain( template ); - if ( astOK ) { - template_domain = astStore( NULL, ptr, - strlen( ptr ) + (size_t) 1 ); - -/* Obtain a pointer to the target domain. */ - target_domain = astGetDomain( target ); - -/* Compare the domain strings for equality. Then free the memory - allocated above. */ - match = astOK && !strcmp( template_domain, target_domain ); - template_domain = astFree( template_domain ); - } - } - } - -/* If the template matches, obtain the values of the template's PreserveAxes - and MatchEnd attributes and determine the number of template axes. */ - if ( astOK && match ) { - preserve_axes = astGetPreserveAxes( template ); - match_end = astGetMatchEnd( template ); - template_naxes = astGetNaxes( template ); - -/* If the PreserveAxes attribute is non-zero, the target axes should be - preserved, so the number of result axes equals the number of target axes. - Otherwise the number of template axes is used. */ - result_naxes = preserve_axes ? target_naxes : template_naxes; - -/* Allocate memory for the arrays of axis associations to be returned. */ - *template_axes = astMalloc( sizeof( int ) * (size_t) result_naxes ); - *target_axes = astMalloc( sizeof( int ) * (size_t) result_naxes ); - if ( astOK ) { - -/* Loop through each of the result axes. */ - for ( result_axis = 0; result_axis < result_naxes; result_axis++ ) { - -/* Set up the axis associations. By default, associate the first result axis - with the first template/target axis. */ - (*template_axes)[ result_axis ] = result_axis; - (*target_axes)[ result_axis ] = result_axis; - -/* However, if the MatchEnd attribute is non-zero, associate the last result - axis with the last template/target axis (this only makes a difference if - there is a difference in the number of axes). */ - if ( match_end ) { - (*template_axes)[ result_axis ] += - template_naxes - result_naxes; - (*target_axes)[ result_axis ] += target_naxes - result_naxes; - } - -/* If any of the associations would be with a template/target axis that doesn't - exist, then use an axis index of -1 for the association instead. */ - if ( ( (*template_axes)[ result_axis ] < 0 ) || - ( (*template_axes)[ result_axis ] >= template_naxes ) ) { - (*template_axes)[ result_axis ] = -1; - } - if ( ( (*target_axes)[ result_axis ] < 0 ) || - ( (*target_axes)[ result_axis ] >= target_naxes ) ) { - (*target_axes)[ result_axis ] = -1; - } - } - -/* Use the target's astSubFrame method to select the required axes from it, - overlaying the template's attributes on to the resulting Frame. This process - also generates the required Mapping between the target and result Frames. */ - match = astSubFrame( target, template, - result_naxes, *target_axes, *template_axes, - map, result ); - } - } - -/* If an error occurred, free any allocated memory and reset the result. */ - if ( !astOK || !match ) { - *template_axes = astFree( *template_axes ); - *target_axes = astFree( *target_axes ); - match = 0; - } - -/* Return the result. */ - return match; -} - -static void MatchAxes( AstFrame *frm1, AstFrame *frm2, int *axes, - int *status ) { -/* -*++ -* Name: -c astMatchAxes -f AST_MATCHAXES - -* Purpose: -* Find any corresponding axes in two Frames. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c void astMatchAxes( AstFrame *frm1, AstFrame *frm2, int *axes ) -f CALL AST_MATCHAXES( FRM1, FRM2, AXES, STATUS ) - -* Class Membership: -* Frame method. - -* 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: -c frm1 -f FRM1 = INTEGER (Given) -* Pointer to the first Frame. -c frm2 -f FRM2 = INTEGER (Given) -* Pointer to the second Frame. -c axes -f AXES = INTEGER( * ) (Returned) -c Pointer to an -f 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. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Applicability: -* Frame -* This function applies to all Frames. - -* Notes: -* - Corresponding axes are identified by the fact that a Mapping can -* be found between them using -c astFindFrame or astConvert. -f AST_FINDFRAME or AST_CONVERT. -* Thus, "corresponding axes" are not necessarily identical. For -* instance, SkyFrame axes in two Frames will match even if they -* describe different celestial coordinate systems -*-- - -* Implementation Notes: -* This function is simply a wrap-up for the protected astMatchAxesX -* method which performs the required processing but swaps the order -* of the first two arguments. This is a trick to allow the -* astMatchAxes method to be over-ridden by derived classes on the -* basis of the class of either of the first two arguments. -* -* In practice, each class that represents an encapsulated Frame (e.g. -* FrameSet, Region, etc) should over-ride this method, extracting a -* Frame from the supplied "frm1" pointer, and then invoking -* astMatchAxesX. - -*/ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Invoke the "astMatchAxesX" method with the first two arguments - swapped. */ - astMatchAxesX( frm2, frm1, axes ); -} - -static void MatchAxesX( AstFrame *frm2, AstFrame *frm1, int *axes, - int *status ) { -/* -*+ -* Name: -* astMatchAxesX - -* Purpose: -* Find any corresponding axes in two Frames. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astMatchAxesX( AstFrame *frm2, AstFrame *frm1, int *axes ) - -* Class Membership: -* Frame method. - -* Description: -* This function performs the processing for the public astMatchAxes -* 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 astMatchAxes method to be over-ridden by derived classes on -* the basis of the class of either of its first two arguments. -* -* See the astMatchAxes method for details of the interface. -*- -*/ - -/* Local Variables: */ - AstFrame *pfrm; - AstFrame *resfrm; - AstMapping *resmap; - int *frm1_axes; - int *pfrm_axes; - int ifirst; - int max_axes; - int min_axes; - int nax2; - int pax; - int preserve_axes; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Temporarily ensure that the PreserveAxes attribute is non-zero in - the second supplied Frame. This means thte result Frame returned by - astMatch below will have the axis count and order of the target Frame - (i.e. "pfrm"). */ - if( astTestPreserveAxes( frm1 ) ) { - preserve_axes = astGetPreserveAxes( frm1 ) ? 1 : 0; - } else { - preserve_axes = -1; - } - astSetPreserveAxes( frm1, 1 ); - -/* Temporarily ensure that the MaxAxes and MinAxes attributes in the - second supplied Frame are set so the Frame can be used as a template - in astMatch for matching any number of axes. */ - if( astTestMaxAxes( frm1 ) ) { - max_axes = astGetMaxAxes( frm1 ); - } else { - max_axes = -1; - } - astSetMaxAxes( frm1, 10000 ); - - if( astTestMinAxes( frm1 ) ) { - min_axes = astGetMinAxes( frm1 ); - } else { - min_axes = -1; - } - astSetMinAxes( frm1, 1 ); - -/* Get the number of axes in the frm2 Frame. */ - nax2 = astGetNaxes( frm2 ); - -/* Loop round the axes in the frm2 Frame. */ - for( ifirst = 0; ifirst < nax2; ifirst++ ) { - -/* Identify the primary Frame defining the current axis in the frm2 - Frame. */ - astPrimaryFrame( frm2, ifirst, &pfrm, &pax ); - -/* Attempt to find a sub-frame within the frm1 Frame that corresponds to - this primary Frame. */ - if( astMatch( frm1, pfrm, 1, &frm1_axes, &pfrm_axes, &resmap, &resfrm ) ) { - -/* Store the one-based index within "frm1" of the corresponding axis. */ - axes[ ifirst ] = frm1_axes[ pax ] + 1; - -/* Free resources */ - frm1_axes = astFree( frm1_axes ); - pfrm_axes = astFree( pfrm_axes ); - resmap = astAnnul( resmap ); - resfrm = astAnnul( resfrm ); - -/* If no corresponding axis was found store zero in the returned array. */ - } else { - axes[ ifirst ] = 0; - } - -/* Free resouces. */ - pfrm = astAnnul( pfrm ); - } - -/* Re-instate the original attribute values in the frm1 Frame. */ - if( preserve_axes == -1 ) { - astClearPreserveAxes( frm1 ); - } else { - astSetPreserveAxes( frm1, preserve_axes ); - } - - if( max_axes == -1 ) { - astClearMaxAxes( frm1 ); - } else { - astSetMaxAxes( frm1, max_axes ); - } - - if( min_axes == -1 ) { - astClearMinAxes( frm1 ); - } else { - astSetMinAxes( frm1, min_axes ); - } -} - -static void NewUnit( AstAxis *ax, const char *old_units, const char *new_units, - const char *method, const char *class, int *status ) { -/* -* Name: -* NewUnit - -* Purpose: -* Modify an Axis Label and Symbol to reflect a new Unit value. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* void NewUnit( AstAxis *ax, const char *old_units, const char *new_units, -* const char *method, const char *class ) - -* Class Membership: -* Frame method. - -* Description: -* This function modifies the Label and Symbol attributes of an Axis -* to reflect a new Unit value. This function should only be called if -* the ActiveUnit flag of the parent Frame is non-zero (this is not -* checked within this function). -* -* If the axis has a set label, then we may be able to modify it to -* correctly describe the axis in the supplied new units. For instance, -* if the original units were "Hz", the original label was "frequency", -* and the new units are "log(Hz)", then the label is modified to become -* "log( frequency )". -* -* The Axis Format attribute is cleared if the supplied units are -* different to the old units (because any set format is probably not -* going to be appropriate for a new system of units. - -* Parameters: -* ax -* Pointer to the Axis. -* old_units -* The original units value. -* new_units -* The new units value. -* 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. -* class -* Pointer to a constant null-terminated character string -* containing the name of the class upon which this function -* was invoked. This is used solely for constructing error messages. - -* Returned Value: -* void. -*/ - -/* Local Variables: */ - AstMapping *map; /* Pointer to units Mapping */ - char *new_lab; /* Pointer to new axis label */ - char *new_sym; /* Pointer to new axis symbol */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Check that the axis label is set. We relay on sub-classes to return - appropriate default labels if the label is not set. */ - if( astTestAxisLabel( ax ) ) { - -/* See if it is possible to map the old units into the new units. - If it is, then a Mapping is returned together with an appropriately - modified label. */ - map = astUnitMapper( old_units, new_units, astGetAxisLabel( ax ), - &new_lab ); - -/* If succesfull, annul the Mapping (which we do not need), and store the - modified label in the Axis, finally freeing the memory used to hold - the modified label. */ - if( map ) { - map = astAnnul( map ); - if( new_lab ) { - astSetAxisLabel( ax, new_lab ); - new_lab = astFree( new_lab ); - } - } - } - -/* Do the same for the axis symbol. */ - if( astTestAxisSymbol( ax ) ) { - map = astUnitMapper( old_units, new_units, astGetAxisSymbol( ax ), - &new_sym ); - if( map ) { - map = astAnnul( map ); - if( new_sym ) { - astSetAxisSymbol( ax, new_sym ); - new_sym = astFree( new_sym ); - } - } - } - -/* If succesful, clear the axis format if the new and old units are - different. */ - if( astOK ) { - if( strcmp( old_units, new_units ) ) astClearAxisFormat( ax ); - } - -} - -static void Norm( AstFrame *this, double value[], int *status ) { -/* -*++ -* Name: -c astNorm -f AST_NORM - -* Purpose: -* Normalise a set of Frame coordinates. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c void astNorm( AstFrame *this, double value[] ) -f CALL AST_NORM( THIS, VALUE, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function normalises a set of Frame coordinate values which -f This routine normalises a set of Frame coordinate values which -* might be unsuitable for display (e.g. may lie outside the -* expected range) into a set of acceptable values suitable for -* display. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c value -f VALUE( * ) = DOUBLE PRECISION (Given and Returned) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). Initially, this should contain a set of -* coordinate values representing a point in the space which the -* Frame describes. If these values lie outside the expected -* range for the Frame, they will be replaced with more -* acceptable (normalised) values. Otherwise, they will be -* returned unchanged. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -* - For some classes of Frame, whose coordinate values are not -* constrained, this function will never modify the values -* supplied. However, for Frames whose axes represent cyclic -* quantities (such as angles or positions on the sky), coordinates -* will typically be wrapped into an appropriate standard range, -* such as zero to 2*pi. -* - The NormMap class is a Mapping which can be used to normalise a -* set of points using the -c astNorm function -f AST_NORM routine -* of a specified Frame. -* - It is intended to be possible to put any set of coordinates -* into a form suitable for display by using this function to -* normalise them, followed by appropriate formatting -c (using astFormat). -f (using AST_FORMAT). -*-- -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - int axis; /* Loop counter for axes */ - int naxes; /* Number of Frame axes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain the number of Frame axes. */ - naxes = astGetNaxes( this ); - -/* Loop to process the coordinate for each axis in turn. */ - for ( axis = 0; axis < naxes; axis++ ) { - -/* Obtain a pointer to the relevant Frame Axis. */ - ax = astGetAxis( this, axis ); - -/* Normalise the coordinate for this axis. */ - astAxisNorm( ax, value + axis ); - -/* Annul the pointer to the Axis. */ - ax = astAnnul( ax ); - -/* Quit looping if an error occurs. */ - if ( !astOK ) break; - } -} - -static void NormBox( AstFrame *this, double lbnd[], double ubnd[], - AstMapping *reg, int *status ) { -/* -*+ -* Name: -* astNormBox - -* Purpose: -* Extend a box to include effect of any singularities in the Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astNormBox( AstFrame *this, double lbnd[], double ubnd[], -* AstMapping *reg ) - -* Class Membership: -* Frame method. - -* 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. -*- -*/ - -/* This base class returns the box limits unchanged. */ -} - -static double Offset2( AstFrame *this, const double point1[2], double angle, - double offset, double point2[2], int *status ){ -/* -*++ -* Name: -c astOffset2 -f AST_OFFSET2 - -* Purpose: -* Calculate an offset along a geodesic curve in a 2D Frame. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c double astOffset2( AstFrame *this, const double point1[2], double angle, -c double offset, double point2[2] ); -f RESULT = AST_OFFSET2( THIS, POINT1, ANGLE, OFFSET, POINT2, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function finds the Frame coordinate values of a point which -f This routine 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: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c point1 -f POINT1( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This should contain the coordinates of the -* point marking the start of the geodesic curve. -c angle -f ANGLE = DOUBLE PRECISION (Given) -* 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. -c offset -f OFFSET = DOUBLE PRECISION -* 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. -c point2 -f POINT2( * ) = DOUBLE PRECISION (Returned) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* in which the coordinates of the required point will be returned. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astOffset2 -f AST_OFFSET2 = DOUBLE PRECISION -* 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: -c - The geodesic curve used by this function is the path of -f - The geodesic curve used by this routine is the path of -* shortest distance between two points, as defined by the -c astDistance function. -f AST_DISTANCE 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: */ - int naxes; /* Number of Frame axes */ - double result; /* Returned value */ - -/* Check the global error status. */ - result = AST__BAD; - if ( !astOK ) return result; - -/* Initialize bad values. */ - point2[ 0 ] = AST__BAD; - point2[ 1 ] = AST__BAD; - -/* Determine the number of Frame axes. */ - naxes = astGetNaxes( this ); - -/* Report an error if the Frame is not 2 dimensional. */ - if( naxes != 2 && astOK ) { - astError( AST__NAXIN, "astOffset2(%s): Invalid number of Frame axes (%d)." - " astOffset2 can only be used with 2 dimensonal Frames.", status, - astGetClass( this ), naxes ); - } - -/* Check the supplied values. */ - if ( astOK && point1[ 0 ] != AST__BAD && point1[ 1 ] != AST__BAD && - angle != AST__BAD && offset != AST__BAD ) { - -/* Store the results. */ - point2[ 0 ] = point1[ 0 ] + sin( angle )*offset; - point2[ 1 ] = point1[ 1 ] + cos( angle )*offset; - -/* The position angle of the curve does not vary in cartesian coordinates */ - result = angle; - - } - -/* Return the result. */ - return result; - -} - -static void Offset( AstFrame *this, const double point1[], - const double point2[], double offset, double point3[], int *status ) { -/* -*++ -* Name: -c astOffset -f AST_OFFSET - -* Purpose: -* Calculate an offset along a geodesic curve. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c void astOffset( AstFrame *this, -c const double point1[], const double point2[], -c double offset, double point3[] ) -f CALL AST_OFFSET( THIS, POINT1, POINT2, OFFSET, POINT3, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function finds the Frame coordinate values of a point which -f This routine finds the Frame coordinate values of a point which -* is offset a specified distance along the geodesic curve between -* two other points. -* -* 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: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c point1 -f POINT1( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This should contain the coordinates of the -* point marking the start of the geodesic curve. -c point2 -f POINT2( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis. -* This should contain the coordinates of the point marking the -* end of the geodesic curve. -c offset -f OFFSET = DOUBLE PRECISION -* 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. -c point3 -f POINT3( * ) = DOUBLE PRECISION (Returned) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* in which the coordinates of the required point will be returned. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -c - The geodesic curve used by this function is the path of -f - The geodesic curve used by this routine is the path of -* shortest distance between two points, as defined by the -c astDistance function. -f AST_DISTANCE 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: */ - double delta; /* Displacement along axis */ - double dist; /* Distance between points */ - double fract; /* Fraction of distance required */ - int axis; /* Loop counter for axes */ - int naxes; /* Number of Frame axes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Determine the number of Frame axes. */ - naxes = astGetNaxes( this ); - if ( astOK ) { - -/* Loop to determine the Cartesian distance between points 1 and 2. */ - dist = 0.0; - for ( axis = 0; axis < naxes; axis++ ) { - -/* If any of the coordinates supplied is bad, set the distance to be - bad and quit looping. */ - if ( ( point1[ axis ] == AST__BAD ) || - ( point2[ axis ] == AST__BAD ) ) { - dist = AST__BAD; - break; - -/* Otherwise, accumulate the sum of squared displacements along each - axis. */ - } else { - delta = point1[ axis ] - point2[ axis ]; - dist += ( delta * delta ); - } - } - -/* Take the square root to find the distance (if valid). */ - if ( dist != AST__BAD ) dist = sqrt( dist ); - -/* If the distance between the points cannot be found, or the distance - is zero but the required offset is non-zero, then set the result - coordinates to be bad. */ - if ( ( dist == AST__BAD ) || - ( ( dist == 0.0 ) && ( offset != 0.0 ) ) ) { - for ( axis = 0; axis < naxes; axis++ ) { - point3[ axis ] = AST__BAD; - } - -/* Otherwise, calculate what fraction of the distance between the - points we need to move, and apply this fraction of the displacement - along each axis. */ - } else { - fract = ( dist == 0.0 ) ? 0.0 : offset / dist; - for ( axis = 0; axis < naxes; axis++ ) { - point3[ axis ] = point1[ axis ] + - fract * ( point2[ axis ] - point1[ axis ] ); - } - } - } -} - -static void Overlay( AstFrame *template, const int *template_axes, - AstFrame *result, int *status ) { -/* -*+ -* Name: -* astOverlay - -* Purpose: -* Overlay the attributes of a template Frame on to another Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astOverlay( AstFrame *template, const int *template_axes, -* AstFrame *result ) - -* Class Membership: -* Frame method. - -* Description: -* This function overlays attributes of one Frame (the "template") 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 Frame, for which 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 template axis to which it corresponds. This array is used -* to establish from which template axis any axis-dependent attributes -* should be obtained. -* -* If any axis in the result Frame is not associated with a template -* 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. -*- -*/ - -/* Local Variables: */ - AstAxis *result_ax; /* Pointer to result Axis object */ - AstAxis *template_ax; /* Pointer to template Axis object */ - AstSystemType sys; /* System value */ - int result_axis; /* Loop counter for result Frame axes */ - int result_naxes; /* Number of result Frame axes */ - int template_axis; /* Index of template Frame axis */ - int template_naxes; /* Number of template Frame axes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Define a macro that tests whether an attribute is set in the template and, - if so, transfers its value to the target. */ -#define OVERLAY(attribute) \ - if ( astTest##attribute( template ) ) { \ - astSet##attribute( result, astGet##attribute( template ) ); \ - } - -/* Use the macro to transfer each Frame attribute in turn. */ - OVERLAY(Dtai); - OVERLAY(Dut1); - OVERLAY(Digits); - OVERLAY(Domain); - OVERLAY(Epoch); - OVERLAY(Title); - OVERLAY(ObsLat) - OVERLAY(ObsLon) - OVERLAY(ObsAlt) - -/* Transfer the ActiveUnit flag. */ - astSetActiveUnit( result, astGetActiveUnit( template ) ); - -/* Only overlay the System and AlignSystem attribute if the values are - valid for the result class. */ - if( astTestSystem( template ) ) { - sys = astGetSystem( template ); - if( astValidateSystem( result, sys, "astOverlay" ) ) { - astSetSystem( result, sys ); - } - } - - if( astTestAlignSystem( template ) ) { - sys = astGetAlignSystem( template ); - if( astValidateSystem( result, sys, "astOverlay" ) ) { - astSetAlignSystem( result, sys ); - } - } - -/* Now transfer attributes associated with individual axes. Obtain the number - of axes in the template and result Frames. */ - template_naxes = astGetNaxes( template ); - result_naxes = astGetNaxes( result ); - if ( astOK ) { - -/* Loop through all the axes in the result Frame and determine to which - template axis each one corresponds. Check that the resulting axis index is - valid. If not, then the axis will not receive new attributes. */ - for ( result_axis = 0; result_axis < result_naxes; result_axis++ ) { - template_axis = template_axes ? template_axes[ result_axis ] : result_axis; - if ( ( template_axis >= 0 ) && ( template_axis < template_naxes ) ) { - -/* Obtain pointers to the relevant Axis objects of each Frame and use the - astAxisOverlay method of the template Axis to overlay attributes on to - the result Axis. Annul the Axis pointers afterwards. */ - template_ax = astGetAxis( template, template_axis ); - result_ax = astGetAxis( result, result_axis ); - astAxisOverlay( template_ax, result_ax ); - template_ax = astAnnul( template_ax ); - result_ax = astAnnul( result_ax ); - -/* Quit looping if an error occurs. */ - if ( !astOK ) break; - } - } - } - -/* Undefine macros local to this function. */ -#undef OVERLAY -} - -static void PermAxes( AstFrame *this, const int perm[], int *status ) { -/* -*+ -* Name: -* astPermAxes - -* Purpose: -* Permute the order of a Frame's axes. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astPermAxes( AstFrame *this, const int perm[] ) - -* Class Membership: -* Frame method. - -* Description: -* This function permutes the order in which a Frame's axes occur. - -* Parameters: -* this -* Pointer to the Frame. -* perm -* An array of int (with one element for each axis of the 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. - -* 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 a Frame, the -* effects are cumulative. -*- - -* Implementation Notes: -* - This function implements the basic astPermAxes method which is -* available via the protected interface to the Frame class. A -* public interface to this method is provided by the -* astPermAxesId_ function. -*/ - -/* Local Variables: */ - int *old; /* Pointer to copy of old permutation array */ - int axis; /* Loop counter for Frame axes */ - int naxes; /* Number of Frame axes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Validate the permutation array, to check that it describes a genuine - permutation. */ - astCheckPerm( this, perm, "astPermAxes" ); - -/* Obtain the number of Frame axes. */ - naxes = astGetNaxes( this ); - -/* Allocate memory and use it to store a copy of the old permutation array for - the Frame. */ - old = astStore( NULL, this->perm, sizeof( int ) * (size_t) naxes ); - -/* Apply the new axis permutation cumulatively to the old one and store the - result in the Frame. */ - if ( astOK ) { - for ( axis = 0; axis < naxes; axis++ ) { - this->perm[ axis ] = old[ perm[ axis ] ]; - } - } - -/* Free the temporary copy of the old array. */ - old = astFree( old ); -} - -static AstFrame *PickAxes( AstFrame *this, int naxes, const int axes[], - AstMapping **map, int *status ) { -/* -*+ -* Name: -* astPickAxes - -* Purpose: -* Create a new Frame by picking axes from an existing one. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* AstFrame *PickAxes( AstFrame *this, int naxes, const int axes[], -* AstMapping **map ) - -* Class Membership: -* Frame method. - -* Description: -* This function creates a new Frame whose axes are copies of axes -* picked from an existing Frame. Other Frame attributes are also -* copied 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 original Frame. -* 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 original and new Frames. The forward -* transformation will convert from the original Frame'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. - -* Returned Value: -* Pointer to the new Frame. - -* Notes: -* - The class of object returned may differ from that of the -* original 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 Frame. Modifying the new Frame will therefore -* not affect the original one. -* - 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. -*- - -* Implementation Notes: -* - This function implements the basic astPickAxes method -* available via the protected interface to the Frame class. The -* public interface to this method is provided by the -* astPickAxesId_ function. -*/ - -/* Local Variables: */ - AstFrame *frame; /* Pointer to Frame to be returned */ - AstMapping *mapping; /* Pointer to Mapping to be returned */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Initialise the returned pointers. */ - frame = NULL; - if ( map ) *map = NULL; - -/* Check that a valid set of axes is being selected . */ - astValidateAxisSelection( this, naxes, axes, "astPickAxes" ); - -/* Create the required new Frame by selecting the axes. This also returns a - Mapping which transforms between the original Frame and the new one. */ - astSubFrame( this, NULL, naxes, axes, NULL, &mapping, &frame ); - if ( astOK ) { - -/* Return the Mapping pointer if required. */ - if ( map ) { - *map = mapping; - -/* Otherwise annul the Mapping. If an error occurs, also annul the Frame. */ - } else { - mapping = astAnnul( mapping ); - if ( !astOK ) frame = astAnnul( frame ); - } - } - -/* Return the pointer to the new Frame. */ - return frame; -} - -static void PrimaryFrame( AstFrame *this, int axis1, - AstFrame **frame, int *axis2, int *status ) { -/* -*+ -* Name: -* astPrimaryFrame - -* Purpose: -* Uniquely identify a primary Frame and one of its axes. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astPrimaryFrame( AstFrame *this, int axis1, AstFrame **frame, -* int *axis2 ) - -* Class Membership: -* Frame method. - -* Description: -* This function returns information about the underlying (primary) Frame -* corresponding to a specified axis, when given what may be a compound -* Frame composed of more than one simpler one. - -* Parameters: -* this -* Pointer to the Frame. -* axis1 -* An axis index (zero-based) identifying the Frame axis for which -* information is required. -* frame -* Address of a location to receive a pointer to the underlying (primary) -* frame to which the requested axis belongs (i.e. this will not be a -* compound Frame). -* axis2 -* Pointer to an int which is to receive the (zero-based) axis -* index within "frame" which identifies the axis being referred -* to, using the axis order that applied when the primary Frame -* was originally constructed (i.e. this function undoes all -* subsequent axis pemutations and the effects of combining -* Frames, in order to reveal the original underlying axis -* order). - -* Notes: -* - This protected method is provided so that class implementations can -* distinguish the axes of frames from one another (e.g. can distinguish -* a longitude axis as being different from a latitide axis) even after -* their order has been permuted and they have been combined with axes from -* other Frames. -* - The reference count of the primary Frame will be incremented by one to -* reflect the new pointer returned. -*- -*/ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Initialise the returned values. */ - *frame = NULL; - *axis2 = 0; - -/* Validate and permute the axis index supplied. */ - axis1 = astValidateAxis( this, axis1, 1, "astPrimaryFrame" ); - -/* Since "this" is a primary Frame (i.e. is not compound), simply clone a - pointer to it. */ - if ( astOK ) *frame = astClone( this ); - -/* Return the permuted axis index, which refers to the original axis order. */ - if ( astOK ) *axis2 = axis1; -} - -double astReadDateTime_( const char *value, int *status ) { -/* -*+ -* Name: -* astReadDateTime - -* Purpose: -* Read a date/time string. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* double astReadDateTime( const char *value ) - -* Class Membership: -* Frame member function. - -* Description: -* This function reads a date/time string in a variety of formats and -* returns the resulting time as a Modified Julian Date. If the string -* cannot be interpreted as a date/time or contains invalid values, an -* error is reported. - -* Parameters: -* value -* Pointer to a null terminated string containing the value to be read. - -* Returned Value: -* The time as a Modified Julian date. - -* Date/Time Formats: -* The date/time formats supported by this function are listed below. These -* are interpreted in a case-insensitive manner and the function is -* generally flexible about the presence of additional white space and the -* use of alternative field delimiters. -* -* Besselian Epoch -* Expressed in decimal years, with or without decimal places -* ("B1950" or "B1976.13", for example). -* Julian Epoch -* Expressed in decimal years, with or without decimal places -* ("J2000" or "J2100.9", for example). -* Year -* Decimal years, with or without decimal places ("1996.8" for example). -* Such values are interpreted as a Besselian epoch (see above) if less -* than 1984.0 and as a Julian epoch otherwise. -* Julian Date -* With or without decimal places ("JD 2454321.9" for example). -* Modified Julian Date -* With or without decimal places ("MJD 54321.4" for example). -* Gregorian Calendar Date -* With the month expressed as an integer or 3-character -* abbreviation, and with optional decimal places to represent a -* fraction of a day ("1996-10-2" or "1996-Oct-2.6" for -* example). If no fractional part of a day is given, the time -* refers to the start of the day (zero hours). -* Gregorian Date and Time -* Any calendar date (as above) but with a fraction of a day expressed -* as hours, minutes and seconds ("1996-Oct-2 12:13:56.985" for example). -* The date and time can be separated by a space or by a "T" (as used -* by ISO8601). - -* Notes: -* - The date/time value is interpreted as a calendar date and time, not -* linked to any particular time system. Thus, interpretation of hours, -* minutes and seconds is done in the obvious manner assuming 86400 seconds -* in a day. No allowance for is made, for instance, for leap seconds or for -* the varying length of a second in some time systems. -* - A value of AST__BAD is returned if this function is invoked with the -* global error status set or if it should fail for any reason. -*- -*/ - -/* Local Vaiables: */ - char cmonth[ 4 ]; /* Buffer for name of month */ - char sep1[ 2 ]; /* Year/month separator string */ - char sep2[ 2 ]; /* Month/day separator string */ - char sep3[ 2 ]; /* Hour/minute separator string */ - char sep4[ 2 ]; /* Minute/second separator string */ - char *cc; /* Pointer to copy of remaining text */ - const char *v; /* Pointer into value string */ - const char *p; /* Pointer to date/time separator */ - double day; /* Day number plus fraction of whole day */ - double epoch; /* Epoch stored as decimal years */ - double hms; /* Hours, min & sec as fraction of a day */ - double jd; /* Julian Date */ - double mjd; /* Modified Julian Date */ - double result; /* Result to be returned */ - double sec; /* Seconds and fractions of a second */ - int hour; /* Number of hours */ - int iday; /* Number of whole days */ - int l; /* Length of string remaining */ - int len; /* Length of string */ - int match; /* Date/time string has correct form? */ - int minute; /* Number of minutes */ - int month; /* Number of months */ - int nc; /* Number of characters read from string */ - int stat; /* Status return from SLALIB functions */ - int year; /* Number of years */ - -/* Check the global error status. */ - if ( !astOK ) return AST__BAD; - -/* Initialise. */ - result = AST__BAD; - -/* Obtain the length of the input string. */ - len = (int) strlen( value ); - -/* Attempt to read the string using each recognised format in turn. */ - -/* Besselian epoch in decimal years (e.g. "B1950.0"). */ -/* ================================================== */ - if ( nc = 0, - ( 1 == astSscanf( value, " %*1[Bb] %lf %n", &epoch, &nc ) ) - && ( nc >= len ) ) { - -/* Convert to Modified Julian Date. */ - result = palEpb2d( epoch ); - -/* Julian epoch in decimal years (e.g. "J2000.0"). */ -/* =============================================== */ - } else if ( nc = 0, - ( 1 == astSscanf( value, " %*1[Jj] %lf %n", &epoch, &nc ) ) - && ( nc >= len ) ) { - -/* Convert to Modified Julian Date. */ - result = palEpj2d( epoch ); - -/* Decimal years (e.g. "1976.2"). */ -/* ============================== */ - } else if ( nc = 0, - ( 1 == astSscanf( value, " %lf %n", &epoch, &nc ) ) - && ( nc >= len ) ) { - -/* Convert to Modified Julian Date, treating the epoch as Julian or Besselian - depending on whether it is 1984.0 or later. */ - result = ( epoch < 1984.0 ) ? palEpb2d( epoch ) : palEpj2d( epoch ); - -/* Modified Julian Date (e.g. "MJD 54321.0"). */ -/* ============================================ */ - } else if ( nc = 0, - ( 1 == astSscanf( value, " %*1[Mm] %*1[Jj] %*1[Dd] %lf %n", - &mjd, &nc ) ) && ( nc >= len ) ) { - -/* Use the result directly. */ - result = mjd; - -/* Julian Date (e.g. "JD 2454321.5"). */ -/* ==================================== */ - } else if ( nc = 0, - ( 1 == astSscanf( value, " %*1[Jj] %*1[Dd] %lf %n", - &jd, &nc ) ) && ( nc >= len ) ) { - -/* Convert to Modified Julian Date. */ - result = jd - 2400000.5; - -/* Gregorian calendar date (e.g. "1996-10-2" or "1996-Oct-2"). */ -/* =========================================================== */ -/* This format also allows day fractions expressed as decimal days, e.g: - - "1996-Oct-2.5001" - - or as hours, minutes and seconds, e.g: - - "1996-Oct-2 12:14:30.52" - - Various alternative field delimiters are also allowed. */ - } else { - -/* Note that the method used to parse this format relies heavily on - conditional execution controlled by "&&" and "||" operators. Initialise - the variables used. */ - v = value; - l = len; - *cmonth = '\0'; - year = month = iday = hour = minute = 0; - day = sec = 0.0; - -/* Identify the year and month. */ -/* ---------------------------- */ -/* Try to match an initial " 1996 - 10 -" or " 1996 10 " or similar. */ - match = - ( nc = 0, ( 4 == astSscanf( v, " %d %1[:/-] %2d %1[:/-]%n", - &year, sep1, &month, sep2, &nc ) ) ); - match = match || - ( nc = 0, ( 4 == astSscanf( v, " %d%1[ ] %2d%1[ ]%n", - &year, sep1, &month, sep2, &nc ) ) ); - -/* If that failed, allow " 1996 - Oct -" or " 1996 Oct " or similar. */ - match = match || - ( nc = 0, ( 4 == astSscanf( v, - " %d %1[:/-] %3[ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "abcdefghijklmnopqrstuvwxyz] %1[:/-]%n", - &year, sep1, cmonth, sep2, &nc ) ) ); - match = match || - ( nc = 0, ( 4 == astSscanf( v, - " %d%1[ ] %3[ABCDEFGHIJKLMNOPQRSTUVWXYZ" - "abcdefghijklmnopqrstuvwxyz]%1[ ]%n", - &year, sep1, cmonth, sep2, &nc ) ) ); - -/* Alternative field separators are permitted above, but ensure that - they are both the same. */ - match = match && ( *sep1 == *sep2 ); - -/* Identify the day and fraction of day. */ -/*-------------------------------------- */ -/* If the above matched correctly, modify the string pointer "v" to - the next character to be interpreted and decrement the remaining - string length. */ - if ( match ) { - v += nc; - l -= nc; - -/* ISO8601 format uses the litter T as a delimiter between the date and time. - If there is a T in the remaining string, take a copy and change the T to - a space. */ - p = strchr( v, 'T' ); - if( p ) { - cc = astStore( NULL, v, l + 1 ); - cc[ p - v ] = ' '; - v = cc; - } else { - cc = NULL; - } - -/* We now try to match the following characters but without reading - any values. This is done to ensure the string has the correct form - (e.g. exclude "-" signs and exponents in numbers, which are - otherwise hard to detect). */ - -/* Try to match " 12.3456 " or similar. */ - match = - ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789].%*[0123456789] %n", - &nc ) ) - && ( nc == l ) ); - -/* If that failed, then try to match " 12. " or similar. */ - match = match || - ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789]. %n", &nc ) ) - && ( nc == l ) ); - -/* If that also failed, then try to match just " 12 " or similar. */ - match = match || - ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789] %n", &nc ) ) - && ( nc == l ) ); - -/* If any of the above patterns matched, now read the data (the day number) - as a double value. */ - if ( match ) { - match = ( nc = 0, ( 1 == astSscanf( v, " %lf %n", &day, &nc ) ) - && ( nc == l ) ); - -/* If none of the above matched, then look to see if the day fraction has been - given in hours, minutes and seconds by trying to match " 12 03 : 45 :" or - " 12 13 45 " or similar. */ - } else { - match = - ( nc = 0, ( 5 == astSscanf( v, - " %2d%*1[ ] %2d %1[:/-] %2d %1[:/-]%n", - &iday, &hour, sep3, &minute, sep4, - &nc ) ) ); - match = match || - ( nc = 0, ( 5 == astSscanf( v, " %2d%*1[ ] %2d%1[ ] %2d%1[ ]%n", - &iday, &hour, sep3, &minute, sep4, - &nc ) ) ); - -/* Alternative field separators are permitted above, but ensure that - they are both the same. */ - match = match && ( *sep3 == *sep4 ); - -/* If the day number was read as an integer, convert it to double. */ - if ( match ) day = (double) iday; - -/* If no match, see if we can get a match without a trailing seconds field. */ - if( !match ) { - match = - ( nc = 0, ( 4 == astSscanf( v, - " %2d%*1[ ] %2d %1[:/-] %2d %n", - &iday, &hour, sep3, &minute, &nc ) && - ( nc == l ) ) ); - match = match || - ( nc = 0, ( 4 == astSscanf( v, " %2d%*1[ ] %2d%1[ ] %2d %n", - &iday, &hour, sep3, &minute, &nc ) && - ( nc == l ) ) ); - -/* If the day number was read as an integer, convert it to double. */ - if ( match ) day = (double) iday; - -/* Otherwise, identify the seconds field. */ -/* -------------------------------------- */ -/* If hours and minutes fields have been matched, now look for the - final seconds (and fractions of seconds) field. This is similar to - the day/fraction field (see earlier) in that we first check that it - has the correct form before reading its value. */ - -/* Adjust the string pointer and remaining string length. */ - } else { - v += nc; - l -= nc; - -/* Try to match " 12.3456 " or similar. */ - match = - ( nc = 0, ( 0 == astSscanf( v, - " %*2[0123456789].%*[0123456789] %n", - &nc ) ) - && ( nc == l ) ); - -/* If that failed, then try to match " 12. " or similar. */ - match = match || - ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789]. %n", &nc ) ) - && ( nc == l ) ); - -/* If that also failed, then try to match just " 12 " or similar. */ - match = match || - ( nc = 0, ( 0 == astSscanf( v, " %*2[0123456789] %n", &nc ) ) - && ( nc == l ) ); - -/* If any of the above patterns matched, now read the data (the number of - seconds) as a double value. */ - if ( match ) { - match = ( nc = 0, ( 1 == astSscanf( v, " %lf %n", &sec, &nc ) ) - && ( nc == l ) ); - } - } - } - -/* Free resources */ - if( cc ) cc = astFree( cc ); - - } - -/* Interpret the values that were read. */ -/* ------------------------------------ */ -/* We execute this if all of the above text matching was successful, - transferred the required number of data values, and consumed the - entire input string. */ - if ( match ) { - -/* See if the month was given as a character string (e.g. "Oct") instead of - a number. If so, define local variables for use in converting it. */ - if ( *cmonth ) { - char lcmonth[ 4 ]; /* Lower case copy of month string */ - const char *ptr; /* Pointer result from look up */ - const char *table = /* Month look up table */ - "jan feb mar apr may jun jul aug sep oct nov dec"; - int i; /* Loop counter for characters */ - -/* Convert the month string to lower case. */ - for ( i = 0; cmonth[ i ]; i++ ) { - lcmonth[ i ] = tolower( cmonth[ i ] ); - } - lcmonth[ i ] = '\0'; - -/* Look the month up in the table of months and generate the required month - number. */ - if ( ( ptr = strstr( table, lcmonth ) ) ) { - month = 1 + ( ptr - table ) / 4; - -/* If the lookup failed, report an error. */ - } else { - astError( AST__DTERR, "Month value \"%s\" is invalid.", status, - cmonth ); - } - } - -/* If OK, extract the integral day number and convert years, months and days - to a Modified Julian Date. */ - if ( astOK ) { - iday = (int) day; - palCaldj( year, month, iday, &mjd, &stat ); - -/* Examine the return status from the conversion and report an appropriate - error if necessary. */ - switch ( stat ) { - case 1: - astError( AST__DTERR, "Year value (%d) is invalid.", status, year ); - break; - case 2: - astError( AST__DTERR, "Month value (%d) is invalid.", status, month ); - break; - case 3: - astError( AST__DTERR, "Day value (%.*g) is invalid.", status, AST__DBL_DIG, - day ); - break; - -/* If conversion to MJD was successful, add any fractional part of a day to the - result. */ - default: - mjd += ( day - (double) iday ); - -/* Convert hours, minutes and seconds to a fraction of a day (this will give - zero if none of these quantities was supplied). */ - palDtf2d( hour, minute, sec, &hms, &stat ); - -/* Examine the return status from the conversion and report an appropriate - error if necessary. */ - switch ( stat ) { - case 1: - astError( AST__DTERR, "Hour value (%d) is invalid.", status, hour ); - break; - case 2: - astError( AST__DTERR, "Minute value (%d) is invalid.", status, - minute ); - break; - case 3: - astError( AST__DTERR, "Seconds value (%.*g) is invalid.", status, - AST__DBL_DIG, sec ); - break; - -/* Add the fraction of a day derived from hours, minutes and seconds fields to - the result. */ - default: - mjd += hms; - break; - } - break; - } - -/* Return the result, if no error occurred. */ - if ( astOK ) result = mjd; - } - -/* If none of the supported date/time formats matched, then report an error. */ - } else { - astError( AST__DTERR, "Date/time does not have the correct form." , status); - } - } - -/* Return the result. */ - return result; -} - -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 Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "mapping.h" -* void ReportPoints( AstMapping *this, int forward, -* AstPointSet *in_points, AstPointSet *out_points, int *status ) - -* Class Membership: -* Frame member function (over-rides the protected astReportPoints -* method inherited from the Mapping class). - -* Description: -* This function reports the coordinates of a set of points before -* and after being transformed by a Frame, by writing them to -* standard output. - -* Parameters: -* this -* Pointer to the Frame. -* forward -* A non-zero value indicates that the Frame'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 Frame was applied. -* out_points -* Pointer to a PointSet which is associated with the -* coordinates of the same set of points after the Frame has -* been applied. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - AstFrame *this; /* Pointer to the Frame structure */ - double **ptr_in; /* Pointer to array of input data pointers */ - double **ptr_out; /* Pointer to array of output data pointers */ - int coord; /* Loop counter for coordinates */ - int ncoord_in; /* Number of input coordinates per point */ - int ncoord_out; /* Number of output coordinates per point */ - int npoint; /* Number of points to report */ - int npoint_in; /* Number of input points */ - int npoint_out; /* Number of output points */ - int point; /* Loop counter for points */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_mapping; - -/* Obtain the numbers of points and coordinates associated with each - PointSet. */ - npoint_in = astGetNpoint( in_points ); - npoint_out = astGetNpoint( out_points ); - ncoord_in = astGetNcoord( in_points ); - ncoord_out = astGetNcoord( out_points ); - -/* Obtain the pointers that give access to the coordinate data - associated with each PointSet. */ - ptr_in = astGetPoints( in_points ); - ptr_out = astGetPoints( out_points ); - -/* In the event that both PointSets don't contain equal numbers of - points (this shouldn't actually happen), simply use the minimum - number. */ - npoint = ( npoint_in < npoint_out ) ? npoint_in : npoint_out; - -/* Loop to report the effect of the transformation on each point in - turn. */ - for ( point = 0; point < npoint; point++ ) { - -/* Report the input coordinates (in parentheses and separated by - commas). Format each value for display using the Frame's astFormat - method. */ - printf( "(" ); - for ( coord = 0; coord < ncoord_in; coord++ ) { - printf( "%s%s", coord ? ", " : "", - astFormat( this, coord, ptr_in[ coord ][ point ] ) ); - } - -/* Similarly report the output coordinates. */ - printf( ") --> (" ); - for ( coord = 0; coord < ncoord_out; coord++ ) { - printf( "%s%s", coord ? ", " : "", - astFormat( this, coord, ptr_out[ coord ][ point ] ) ); - } - printf( ")\n" ); - } -} - -static void Resolve( AstFrame *this, const double point1[], - const double point2[], const double point3[], - double point4[], double *d1, double *d2, int *status ){ -/* -*++ -* Name: -c astResolve -f AST_RESOLVE - -* Purpose: -* Resolve a vector into two orthogonal components - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c void astResolve( AstFrame *this, const double point1[], -c const double point2[], const double point3[], -c double point4[], double *d1, double *d2 ); -f CALL AST_RESOLVE( THIS, POINT1, POINT2, POINT3, POINT4, D1, D2, -f STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function resolves a vector into two perpendicular components. -f This routine 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: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c point1 -f POINT1( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This marks the start of the basis vector, -* and of the vector to be resolved. -c point2 -f POINT2( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This marks the end of the basis vector. -c point3 -f POINT3( * ) = DOUBLE PRECISION (Given) -c An array of double, with one element for each Frame axis -f An array with one element for each Frame axis -* (Naxes attribute). This marks the end of the vector to be -* resolved. -c point4 -f POINT4( * ) = DOUBLE PRECISION (Returned) -c An array of double, with one element for each Frame axis -f An array 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. -c d1 -f D1 = DOUBLE PRECISION (Returned) -c The address of a location at which to return the distance from -f 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. -c d2 -f D2 = DOUBLE PRECISION (Returned) -c The address of a location at which to return the distance from -f 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. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -c - Each vector used in this function is the path of -f - Each vector used in this routine is the path of -* shortest distance between two points, as defined by the -c astDistance function. -f AST_DISTANCE 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: */ - double bv; /* Length of basis vector */ - double c; /* Component length */ - double dp; /* Dot product */ - int axis; /* Loop counter for axes */ - int naxes; /* Number of Frame axes */ - int ok; /* OK to proceed? */ - -/* Check the global error status. */ - *d1 = AST__BAD; - *d2 = AST__BAD; - if ( !astOK ) return; - -/* Determine the number of Frame axes. */ - naxes = astGetNaxes( this ); - -/* Initialize bad values, and check if the supplied vectors are good. */ - ok = 1; - for( axis = 0; axis < naxes; axis++ ){ - point4[ axis ] = AST__BAD; - if( point1[ axis ] == AST__BAD || - point2[ axis ] == AST__BAD || - point3[ axis ] == AST__BAD ) ok = 0; - } - -/* Check the supplied values. */ - if ( ok ) { - -/* Find the dot product of the basis vector with the vector joining point 1 - and point 3. At the same time form the squared length of the basis - vector. */ - dp = 0.0; - bv = 0.0; - for( axis = 0; axis < naxes; axis++ ){ - c = point2[ axis ] - point1[ axis ]; - dp += c * ( point3[ axis ] - point1[ axis ] ); - bv += c * c; - } - -/* Check the basis vector does not have zero length, and convert the - squared length into a length. */ - if( bv > 0.0 ) { - bv = sqrt( bv ); - -/* The dot product is the required distance d1 multiplied by the length - of the basis vector. Form the distance d1. */ - *d1 = dp/bv; - -/* Offset away from point 1 towards point 2 by a distance of d1. */ - for( axis = 0; axis < naxes; axis++ ){ - point4[ axis ] = point1[ axis ] + - (*d1/bv)*( point2[ axis ] - point1[ axis ] ); - } - -/* Finally, form the required length d2. */ - *d2 = 0.0; - for( axis = 0; axis < naxes; axis++ ){ - c = ( point3[ axis ] - point4[ axis ] ); - *d2 += c*c; - } - *d2 = sqrt( *d2 ); - - } - } - - return; - -} - -static AstPointSet *ResolvePoints( AstFrame *this, const double point1[], - const double point2[], AstPointSet *in, - AstPointSet *out, int *status ) { -/* -*+ -* Name: -* astResolvePoints - -* Purpose: -* Resolve a set of vectors into orthogonal components - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* AstPointSet *astResolvePoints( AstFrame *this, const double point1[], -* const double point2[], AstPointSet *in, -* AstPointSet *out ) - -* Class Membership: -* Frame method. - -* 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 be signed only if the Frame is 2-dimensional, in which -* case a positive value indicates that rotation from the basis vector -* to the tested vector is in the same sense as rotation from the first -* to the second axis of the Frame. - -* 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. -* - We assume flat geometry throughout this function. Other classes, -* (e.g. SkyFrame) will override this method using more appropriate -* geometry. -*- -*/ - -/* Local Variables: */ - AstPointSet *result; /* Pointer to output PointSet */ - double **ptr_in; /* Pointers to input axis values */ - double **ptr_out; /* Pointers to returned axis values */ - double *basisv; /* Pointer to array holding basis vector */ - double *d1; /* Pointer to next parallel component value */ - double *d2; /* Pointer to next perpendicular component value */ - double *ip; /* Pointer to next input axis value */ - double bv; /* Length of basis vector */ - double c; /* Constant value */ - double d; /* Component length */ - double dp; /* Dot product */ - double x1; /* First axis of basis vector */ - double x2; /* First axis of test vector */ - double y1; /* Second axis of basis vector */ - double y2; /* Second axis of test vector */ - int axis; /* Loop counter for axes */ - int ipoint; /* Index of next point */ - int nax; /* Number of Frame axes */ - int ncoord_in; /* Number of input PointSet coordinates */ - int ncoord_out; /* Number of coordinates in output PointSet */ - int npoint; /* Number of points to transform */ - int npoint_out; /* Number of points in output PointSet */ - int ok; /* OK to proceed? */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain the number of axes in the Frame. */ - nax = astGetNaxes( this ); - -/* Obtain the number of input vectors to resolve and the number of coordinate - values per vector. */ - npoint = astGetNpoint( in ); - ncoord_in = astGetNcoord( in ); - -/* If OK, check that the number of input coordinates matches the number - required by the Frame. Report an error if these numbers do not match. */ - if ( astOK && ( ncoord_in != nax ) ) { - astError( AST__NCPIN, "astResolvePoints(%s): Bad number of coordinate " - "values (%d) in input %s.", status, astGetClass( this ), ncoord_in, - astGetClass( in ) ); - astError( AST__NCPIN, "The %s given requires %d coordinate value(s) for " - "each input point.", status, astGetClass( this ), nax ); - } - -/* If still OK, and a non-NULL pointer has been given for the output PointSet, - then obtain the number of points and number of coordinates per point for - this PointSet. */ - if ( astOK && out ) { - npoint_out = astGetNpoint( out ); - ncoord_out = astGetNcoord( out ); - -/* Check that the dimensions of this PointSet are adequate to accommodate the - output coordinate values and report an error if they are not. */ - if ( astOK ) { - if ( npoint_out < npoint ) { - astError( AST__NOPTS, "astResolvePoints(%s): Too few points (%d) in " - "output %s.", status, astGetClass( this ), npoint_out, - astGetClass( out ) ); - astError( AST__NOPTS, "The %s needs space to hold %d transformed " - "point(s).", status, astGetClass( this ), npoint ); - } else if ( ncoord_out < 2 ) { - astError( AST__NOCTS, "astResolvePoints(%s): Too few coordinate " - "values per point (%d) in output %s.", status, - astGetClass( this ), ncoord_out, astGetClass( out ) ); - astError( AST__NOCTS, "The %s supplied needs space to store 2 " - "coordinate value(s) per transformed point.", status, - astGetClass( this ) ); - } - } - } - -/* If all the validation stages are passed successfully, and a NULL output - pointer was given, then create a new PointSet to encapsulate the output - coordinate data. */ - if ( astOK ) { - if ( !out ) { - result = astPointSet( npoint, 2, "", status ); - -/* Otherwise, use the PointSet supplied. */ - } else { - result = out; - } - } - -/* Get pointers to the input and output axis values */ - ptr_in = astGetPoints( in ); - ptr_out = astGetPoints( result ); - -/* Store points to the first two axis arrays in the returned PointSet. */ - d1 = ptr_out[ 0 ]; - d2 = ptr_out[ 1 ]; - -/* Allocate work space. */ - basisv = astMalloc( sizeof( double )*(size_t) nax ); - -/* If the Frame has only one axis, then the supplied basic vector is - irrelevant - the returned perpendicular distances are always zero and - the returned parallel distances are just the distances from point1 - to each input point. */ - if( nax < 2 && basisv ) { - ip = ptr_in[ 0 ]; - for( ipoint = 0; ipoint < npoint; ipoint++, d1++, d2++, ip++ ) { - *d1 = astAxDistance( this, 1, point1[0], *ip ); - *d2 = 0.0; - } - -/* Now deal with Frames which have 2 or more axes */ - } else if( basisv ){ - -/* Check if the supplied positions defining the basis vector are good. - Store the basis vector, and get its squared length. */ - ok = 1; - bv = 0.0; - for( axis = 0; axis < nax; axis++ ){ - if( point1[ axis ] == AST__BAD || - point2[ axis ] == AST__BAD ) { - ok = 0; - break; - } else { - basisv[ axis ] = point2[ axis ] - point1[ axis ]; - bv += basisv[ axis ]*basisv[ axis ]; - } - } - -/* Check the basis vector does not have zero length, and convert the - squared length into a length. */ - if( ok && bv > 0.0 ) { - bv = sqrt( bv ); - } else { - ok = 0; - } - -/* Store points to the first two axis arrays in the returned PointSet. */ - d1 = ptr_out[ 0 ]; - d2 = ptr_out[ 1 ]; - -/* Check supplied values can be used */ - if( ok ) { - -/* Loop round each supplied vector. */ - for( ipoint = 0; ipoint < npoint; ipoint++, d1++, d2++ ) { - -/* Find the dot product of the basis vector with the vector joining point 1 - and the end of the current vector. */ - ok = 1; - dp = 0.0; - for( axis = 0; axis < nax; axis++ ){ - d = ptr_in[ axis ][ ipoint ] - point1[ axis ]; - if( d != AST__BAD ) { - dp += basisv[ axis ] * d; - } else { - ok = 0; - break; - } - } - -/* If this input position is good... */ - if( ok ) { - -/* The dot product is the required parallel component length multiplied by the - length of the basis vector. Form the distance d1. */ - *d1 = dp/bv; - -/* Offset away from point 1 towards point 2 by a distance of d1, and form the - required length d2. */ - c = *d1/bv; - if( nax > 2 ) { - *d2 = 0.0; - for( axis = 0; axis < nax; axis++ ){ - d = ptr_in[ axis ][ ipoint ] - - ( point1[ axis ] + c*basisv[ axis ] ); - *d2 += d*d; - } - *d2 = sqrt( *d2 ); - -/* If the Frame is 2 dimensional, we can give a sign the the perpendicular - component. */ - } else { - x1 = c*basisv[ 0 ]; - y1 = c*basisv[ 1 ]; - x2 = ptr_in[ 0 ][ ipoint ] - ( point1[ 0 ] + x1 ); - y2 = ptr_in[ 1 ][ ipoint ] - ( point1[ 1 ] + y1 ); - *d2 = sqrt( x2*x2 + y2*y2 ); - if( x1*y2 - x2*y1 < 0.0 ) *d2 = -(*d2); - } - -/* If this input vector is bad, put bad values in the output */ - } else { - *d1 = AST__BAD; - *d2 = AST__BAD; - } - } - -/* If supplied values cannot be used, fill the returned PointSet with bad - values */ - } else { - for( ipoint = 0; ipoint < npoint; ipoint++, d1++, d2++ ) { - *d1 = AST__BAD; - *d2 = AST__BAD; - } - } - } - -/* Free resources */ - basisv = astFree( basisv ); - -/* Annul the returned PointSet if an error occurred. */ - if( !astOK ) result = astAnnul( result ); - -/* Return a pointer to the output PointSet. */ - return result; -} - -static void SetActiveUnit( AstFrame *this, int value, int *status ){ -/* -*++ -* Name: -c astSetActiveUnit -f AST_SETACTIVEUNIT - -* Purpose: -* Specify how the Unit attribute should be used. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c void astSetActiveUnit( AstFrame *this, int value ) -f CALL AST_SETACTIVEUNIT( THIS, VALUE, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function -f This routine -* sets the current value of the ActiveUnit flag for a Frame, which -* controls how the Frame behaves when it is used (by -c astFindFrame or astConvert) -f AST_FINDFRAME or AST_CONVERT) -* to match another Frame. If the ActiveUnit flag is set in both -* template and target Frames then the returned Mapping takes into account -* any differences in axis units. The default value for simple Frames is -* zero, which preserves the behaviour of versions of AST prior to -* version 2.0. -* -* If the ActiveUnit flag of either Frame is -c zero, -f .FALSE., -* then the Mapping will ignore any difference in the Unit attributes of -* corresponding template and target axes. In this mode, the Unit -* attributes are purely descriptive commentary for the benefit of -* human readers and do not influence the Mappings between Frames. -* This is the behaviour which all Frames had in older version of AST, -* prior to the introduction of this attribute. -* -* If the ActiveUnit flag of both Frames is -c non-zero, -f .TRUE., -* then the Mapping from template to target will take account of any -* difference in the axis Unit attributes, where-ever possible. For -* instance, if corresponding target and template axes have Unit strings of -* "km" and "m", then the FrameSet class will use a ZoomMap to connect -* them which introduces a scaling of 1000. If no Mapping can be found -* between the corresponding units string, then an error is reported. -* In this mode, it is assumed that values of the Unit attribute conform -* to the syntax for units strings described in the FITS WCS Paper I -* "Representations of world coordinates in FITS" (Greisen & Calabretta). -* Particularly, any of the named unit symbols, functions, operators or -* standard multiplier prefixes listed within that paper can be used within -* a units string. A units string may contain symbols for unit which are -* not listed in the FITS paper, but transformation to any other units -* will then not be possible (except to units which depend only on the -* same unknown units - thus "flops" can be transformed to "Mflops" -* even though "flops" is not a standard FITS unit symbol). -* -* A range of common non-standard variations of unit names and multiplier -* prefixes are also allowed, such as adding an "s" to the end of Angstrom, -* using a lower case "a" at the start of "angstrom", "micron" instead of -* "um", "sec" instead of "s", etc. -* -c If the ActiveUnit flag is non-zero, setting a new Unit value for an -f If the ActiveUnit flag is .TRUE., setting a new Unit value for an -* axis may also change its Label and Symbol attributes. For instance, if -* an axis has Unit "Hz" and Label "frequency", then changing its Unit to -* "log(Hz)" will change its Label to "log( frequency )". In addition, -* the Axis Format attribute will be cleared when-ever a new value -* is assigned to the Unit attribute. -* -c Note, if a non-zero value is set for the ActiveUnit flag, then changing a -f Note, if a .TRUE. value is set for the ActiveUnit flag, then changing a -* Unit value for the current Frame within a FrameSet will result in the -* Frame being re-mapped (that is, the Mappings which define the -* relationships between Frames within the FrameSet will be modified to -* take into account the change in Units). - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c value -f VALUE = LOGICAL (Given) -* The new value to use. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Applicability: -* SkyFrame -c The ActiveUnit flag for a SkyFrame is always 0 (any value -c supplied using this function is ignored). -f The ActiveUnit flag for a SkyFrame is always .FALSE. (any value -f supplied using this routine is ignored). -* SpecFrame -c The ActiveUnit flag for a SpecFrame is always 1 (any value -c supplied using this function is ignored). -f The ActiveUnit flag for a SpecFrame is always .TRUE. (any value -f supplied using this routine is ignored). -* FluxFrame -c The ActiveUnit flag for a FluxFrame is always 1 (any value -c supplied using this function is ignored). -f The ActiveUnit flag for a FluxFrame is always .TRUE. (any value -f supplied using this routine is ignored). -* CmpFrame -c The default ActiveUnit flag for a CmpFrame is 1 if both of the -c component Frames are using active units, and zero otherwise. When -f The default ActiveUnit flag for a CmpFrame is .TRUE. if both of the -f component Frames are using active units, and .FALSE. otherwise. When -* a new value is set for the ActiveUnit flag, the flag value -* is propagated to the component Frames. This change will be -* reflected through all references to the component Frames, not -* just those encapsulated within the CmpFrame. -* Region: -* Regions always use active units if possible. - -* Notes: -* - The ActiveUnit flag resembles a Frame attribute, except that it -* cannot be tested or cleared, and it cannot be accessed using the -c generic astGet<X> and astSet<X> functions. -f generic AST_GET<X> and AST_SET<X> routines. -c - The astGetActiveUnit function can be used to retrieve the current -f - The AST_GETACTIVEUNIT routine can be used to retrieve the current -* value of the ActiveUnit flag. - -*-- -*/ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Store a value of 1 for the Frame component if the supplied value is - non-zero. */ - this->active_unit = ( value ) ? 1 : 0; -} - -static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { -/* -* Name: -* SetAttrib - -* Purpose: -* Set an attribute value for a Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* void SetAttrib( AstObject *this, const char *setting, int *status ) - -* Class Membership: -* Frame member function (over-rides the astSetAttrib method inherited -* from the Mapping class). - -* Description: -* This function assigns an attribute value for a Frame, 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 Frame. -* setting -* Pointer to a null terminated string specifying the new attribute -* value. -* status -* Pointer to the inherited status variable. - -* Notes: -* - This function uses one-based axis numbering so that it is -* suitable for external (public) use. -*/ - -/* Local Vaiables: */ - AstAxis *ax; /* Pointer to Axis */ - AstFrame *pfrm; /* Pointer to primary Frame containing axis */ - AstFrame *this; /* Pointer to the Frame structure */ - AstSystemType system_code; /* System code */ - char pfrm_attrib[ 100 ]; /* Primary Frame attribute */ - char *pfrm_setting; /* Primary Frame attribute */ - char *axis_setting; /* Pointer to axis attribute setting string */ - const char *equals; /* Pointer to equals sign */ - const char *old_setting; /* Pointer to supplied setting string */ - const char *op; /* Pointer to opening parenthesis */ - double dval; /* Double attibute value */ - double mjd; /* Epoch as a Modified Julian Date */ - int axis; /* Index for the Frame axis */ - int axis_nc; /* No. characters in axis attribute name */ - int axis_value; /* Offset of value to be assigned to axis */ - int digits; /* Number of digits of precision */ - int direction; /* Axis direction flag */ - int domain; /* Offset of Domain string */ - int epoch; /* Offset of Epoch string */ - int format; /* Offset of axis Format string */ - int free_axis_setting; /* Should axis_setting be freed? */ - int has_axis; /* Does setting include an axis specifier? */ - int ival; /* Integer attribute value */ - int label; /* Offset of axis Label string */ - int len; /* Length of setting string */ - int match_end; /* Match final axes of target? */ - int max_axes; /* Maximum number of axes matched */ - int min_axes; /* Minimum number of axes matched */ - int nc; /* Number of characters read by astSscanf */ - int off2; /* Modified offset of attribute value */ - int off; /* Offset of attribute value */ - int oldrep; /* Original error reporting state */ - int paxis; /* Axis index within primary frame */ - int permute; /* Permute axes in order to match? */ - int preserve_axes; /* Preserve matched target axes? */ - int sign; /* Sign of longitude value */ - int symbol; /* Offset of axis Symbol string */ - int system; /* Offset of System string */ - int title; /* Offset of Title string */ - int unit; /* Offset of axis Unit string */ - int used; /* Could the setting string be used? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_object; - -/* Find the offset to the first equal sign in the setting string. */ - equals = strchr( setting, '=' ); - -/* Set a flag indicating if the attribute name includes an axis - specifier. */ - op = strchr( setting, '(' ); - has_axis = ( !op || op > equals ) ? 0 : 1; - -/* A flag indicating that we do not need to free the axis_setting memory. */ - free_axis_setting = 0; - -/* Initialise things to avoid compiler warnings. */ - axis_setting = NULL; - old_setting = NULL; - -/* Jump back to here if we are trying the same attribute setting but with - an explicit axis "(1)" added to the attribute name. */ -L1: - -/* 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. */ - -/* Digits. */ -/* ------- */ - if ( nc = 0, - ( 1 == astSscanf( setting, "digits= %d %n", &digits, &nc ) ) - && ( nc >= len ) ) { - astSetDigits( this, digits ); - -/* Digits(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 2 == astSscanf( setting, "digits(%d)= %d %n", - &axis, &digits, &nc ) ) - && ( nc >= len ) ) { - -/* There is no function to set the Digits attribute value for an axis - directly, so obtain a pointer to the Axis and use this to set the - attribute. */ - (void) astValidateAxis( this, axis - 1, 1, "astSetDigits(axis)" ); - ax = astGetAxis( this, axis - 1 ); - astSetAxisDigits( ax, digits ); - ax = astAnnul( ax ); - -/* Direction(axis). */ -/* ---------------- */ - } else if ( nc = 0, - ( 2 == astSscanf( setting, "direction(%d)= %d %n", - &axis, &direction, &nc ) ) - && ( nc >= len ) ) { - astSetDirection( this, axis - 1, direction ); - -/* Epoch. */ -/* ------ */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "epoch=%n%*[^\n]%n", &epoch, &nc ) ) - && ( nc >= len ) ) { - -/* Convert the Epoch value to a Modified Julian Date before use. */ - mjd = astReadDateTime( setting + epoch ); - if ( astOK ) { - astSetEpoch( this, mjd ); - -/* Report contextual information if the conversion failed. */ - } else { - astError( AST__ATTIN, "astSetAttrib(%s): Invalid epoch value " - "\"%s\" given for coordinate system.", status, - astGetClass( this ), setting + epoch ); - } - -/* Top(axis). */ -/* ---------- */ - } else if ( nc = 0, - ( 2 == astSscanf( setting, "top(%d)= %lg %n", - &axis, &dval, &nc ) ) - && ( nc >= len ) ) { - astSetTop( this, axis - 1, dval ); - -/* Bottom(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 2 == astSscanf( setting, "bottom(%d)= %lg %n", - &axis, &dval, &nc ) ) - && ( nc >= len ) ) { - astSetBottom( this, axis - 1, dval ); - -/* Domain. */ -/* ------- */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "domain=%n%*[^\n]%n", &domain, &nc ) ) - && ( nc >= len ) ) { - astSetDomain( this, setting + domain ); - -/* Format(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "format(%d)=%n%*[^\n]%n", - &axis, &format, &nc ) ) - && ( nc >= len ) ) { - astSetFormat( this, axis - 1, setting + format ); - -/* Label(axis). */ -/* ------------ */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "label(%d)=%n%*[^\n]%n", - &axis, &label, &nc ) ) - && ( nc >= len ) ) { - astSetLabel( this, axis - 1, setting + label ); - -/* MatchEnd. */ -/* --------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "matchend= %d %n", &match_end, &nc ) ) - && ( nc >= len ) ) { - astSetMatchEnd( this, match_end ); - -/* MaxAxes. */ -/* -------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "maxaxes= %d %n", &max_axes, &nc ) ) - && ( nc >= len ) ) { - astSetMaxAxes( this, max_axes ); - -/* MinAxes. */ -/* -------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "minaxes= %d %n", &min_axes, &nc ) ) - && ( nc >= len ) ) { - astSetMinAxes( this, min_axes ); - -/* Permute. */ -/* -------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "permute= %d %n", &permute, &nc ) ) - && ( nc >= len ) ) { - astSetPermute( this, permute ); - -/* PreserveAxes. */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "preserveaxes= %d %n", - &preserve_axes, &nc ) ) - && ( nc >= len ) ) { - astSetPreserveAxes( this, preserve_axes ); - -/* Symbol(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "symbol(%d)=%n%*[^\n]%n", - &axis, &symbol, &nc ) ) - && ( nc >= len ) ) { - astSetSymbol( this, axis - 1, setting + symbol ); - -/* AlignSystem. */ -/* ------------ */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "alignsystem= %n%*s %n", &system, &nc ) ) - && ( nc >= len ) ) { - -/* Convert the string to a System code before use. */ - system_code = astSystemCode( this, system + setting ); - if ( system_code != AST__BADSYSTEM ) { - astSetAlignSystem( this, system_code ); - -/* Report an error if the string value wasn't recognised. */ - } else { - astError( AST__ATTIN, - "astSetAttrib(%s): Invalid AlignSystem description \"%s\".", status, - astGetClass( this ), system + setting ); - } - -/* System. */ -/* ------- */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "system= %n%*s %n", &system, &nc ) ) - && ( nc >= len ) ) { - -/* Convert the string to a System code before use. */ - system_code = astSystemCode( this, system + setting ); - if ( system_code != AST__BADSYSTEM ) { - astSetSystem( this, system_code ); - -/* Report an error if the string value wasn't recognised. */ - } else { - astError( AST__ATTIN, - "astSetAttrib(%s): Invalid System description \"%s\".", status, - astGetClass( this ), system + setting ); - } - -/* Title. */ -/* ------ */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "title=%n%*[^\n]%n", &title, &nc ) ) - && ( nc >= len ) ) { - astSetTitle( this, setting + title ); - -/* Unit(axis). */ -/* ----------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "unit(%d)=%n%*[^\n]%n", - &axis, &unit, &nc ) ) - & ( nc >= len ) ) { - astSetUnit( this, axis - 1, setting + unit ); - -/* ObsLat. */ -/* ------- */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "obslat=%n%*s %n", &off, &nc ) ) - && ( nc >= 7 ) ) { - -/* If the first character in the value string is "N" or "S", remember the - sign of the value and skip over the sign character. Default is north - (+ve). */ - off2 = off; - if( setting[ off ] == 'N' || setting[ off ] == 'n' ) { - off2++; - sign = +1; - } else if( setting[ off ] == 'S' || setting[ off ] == 's' ) { - off2++; - sign = -1; - } else { - sign = +1; - } - -/* If not already created, create an FK5 J2000 SkyFrame which will be used - for formatting and unformatting ObsLon and ObsLat values. */ - if( !skyframe ) { - astBeginPM; - skyframe = astSkyFrame( "system=FK5,equinox=J2000,format(2)=dms.2", status ); - astEndPM; - } - -/* Convert the string to a radians value before use. */ - ival = astUnformat( skyframe, 1, setting + off2, &dval ); - if ( ival == astChrLen( setting ) - off2 ) { - astSetObsLat( this, dval*sign ); - -/* Report an error if the string value wasn't recognised. */ - } else { - astError( AST__ATTIN, "astSetAttrib(%s): Invalid value for " - "ObsLat (observers latitude) \"%s\".", status, astGetClass( this ), - setting + off ); - } - -/* ObsLon. */ -/* ------- */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "obslon=%n%*s %n", &off, &nc ) ) - && ( nc >= 7 ) ) { - -/* If the first character in the value string is "E" or "W", remember the - sign of the value and skip over the sign character. Default is east - (+ve). */ - off2 = off; - if( setting[ off ] == 'E' || setting[ off ] == 'e' ) { - off2++; - sign = +1; - } else if( setting[ off ] == 'W' || setting[ off ] == 'w' ) { - off2++; - sign = -1; - } else { - sign = +1; - } - -/* If not already created, create an FK5 J2000 SkyFrame which will be used - for formatting and unformatting ObsLon and ObsLat values. */ - if( !skyframe ) { - astBeginPM; - skyframe = astSkyFrame( "system=FK5,equinox=J2000,format(2)=dms.2", status ); - astEndPM; - } - -/* Convert the string to a radians value before use. */ - ival = astUnformat( skyframe, 1, setting + off2, &dval ); - if ( ival == astChrLen( setting ) - off2 ) { - astSetObsLon( this, dval*sign ); - -/* Report an error if the string value wasn't recognised. */ - } else { - astError( AST__ATTIN, "astSetAttrib(%s): Invalid value for " - "ObsLon (observers longitude) \"%s\".", status, astGetClass( this ), - setting + off ); - } - -/* ObsAlt. */ -/* ------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "obsalt= %lg %n", &dval, &nc ) ) - && ( nc >= len ) ) { - astSetObsAlt( this, dval ); - -/* Dtai. */ -/* ---- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "dtai= %lg %n", &dval, &nc ) ) - && ( nc >= len ) ) { - astSetDtai( this, dval ); - -/* Dut1. */ -/* ---- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "dut1= %lg %n", &dval, &nc ) ) - && ( nc >= len ) ) { - astSetDut1( this, dval ); - - -/* Read-only attributes. */ -/* --------------------- */ -/* Define a macro 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 ) ) - -/* Use this macro to report an error if a read-only attribute has been - specified. */ - } else if ( MATCH( "naxes" ) || - !strncmp( setting, "normunit", 8 ) || - !strncmp( setting, "internalunit", 12 ) ) { - 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); - -/* Other axis attributes. */ -/* ---------------------- */ -/* If the attribute was not identified above, but appears to refer to - a Frame axis, then it may refer to an Axis object of a derived type - (which has additional attributes not recognised here). */ - } else if ( !free_axis_setting && ( nc = 0, - ( 1 == astSscanf( setting, "%*[^()=]%n(%d)%n=%*[^\n]%n", - &axis_nc, &axis, &axis_value, &nc ) ) - && ( nc >= len ) ) ) { - -/* Validate the axis index and copy the attribute setting string. */ - (void) astValidateAxis( this, axis - 1, 1, "astSet" ); - axis_setting = astString( setting, len ); - if ( astOK ) { - -/* Over-write the axis index in the copy with the value to be - assigned. */ - (void) strcpy( axis_setting + axis_nc, setting + axis_value ); - -/* Obtain a pointer to the Axis object. */ - ax = astGetAxis( this, axis - 1 ); - if( astOK ) { - -/* Assume that we will be able to use the setting. */ - used = 1; - -/* Temporarily switch off error reporting so that if the following attempt - to access the axis attribute fails, we can try to interpret the - attribute name as an attribute of the primary Frame containing the - specified axis. Any errors reported in this context will simply be - ignored, in particularly they are not deferred for later delivery. */ - oldrep = astReporting( 0 ); - -/* Use the Axis astSetAttrib method - to set the value. */ - astSetAttrib( ax, axis_setting ); - -/* If the above call failed with a status of AST__BADAT, indicating that - the attribute name was not recognised, clear the status so that we can - try to interpret the attribute name as an attribute of the primary Frame - containing the specified axis. */ - if( astStatus == AST__BADAT ) { - astClearStatus; - -/* Find the primary Frame containing the specified axis. */ - astPrimaryFrame( this, axis - 1, &pfrm, &paxis ); - -/* Only attempt to use the primary Frame if it is not the same as "this" - - otherwise we could end up in an infinite loop. */ - if( pfrm != this ) { - -/* astPrimaryFrame returns the original - unpermuted - axis index within - the primary Frame. So we need to take into account any axis permutation - which has been applied to the primary Frame when forming the attribute name - to use below. Find the permuted (external) axis index which corresponds to - the internal (unpermuted) axis index "paxis". */ - paxis = astValidateAxis( pfrm, paxis, 0, "astSet" ); - -/* Modify the attribute name to refer to the axis numbering of the - primary frame. */ - sprintf( pfrm_attrib, "%.*s(%d)", axis_nc, setting, paxis + 1 ); - -/* Create a setting string in which the attribute name refers to the axis - numbering of the primary frame. */ - pfrm_setting = NULL; - nc = 0; - pfrm_setting = astAppendString( pfrm_setting, &nc, pfrm_attrib ); - pfrm_setting = astAppendString( pfrm_setting, &nc, setting + axis_value ); - -/* Attempt to set the attribute within the primary Frame. */ - astSetAttrib( pfrm, pfrm_setting ); - -/* Free the memory. */ - pfrm_setting = astFree( pfrm_setting ); - -/* If this failed, clear the status and indicate that we have not managed to - use the attribute setting. */ - if( !astOK ) { - astClearStatus; - used = 0; - } - - } else { - used = 0; - } - -/* If not found attempt to set the attribute value in the Axis, omitting - the axis index. */ - if( ! used ) { - astSetAttrib( pfrm, axis_setting ); - if( !astOK ) { - astClearStatus; - } else { - used = 1; - } - } - -/* Free the setting string, and annul the primary Frame pointer. */ - pfrm = astAnnul( pfrm ); - } - -/* Re-instate the original error reporting state. */ - astReporting( oldrep ); - -/* If we could not use the setting, attempt to set the axis attribute again, - this time retaining the error report. This is done to ensure the user - gets an appropriate error message. */ - if( !used ) astSetAttrib( ax, axis_setting ); - } - -/* Annul the Axis pointer and free the memory holding the attribute - setting. */ - ax = astAnnul( ax ); - } - axis_setting = astFree( axis_setting ); - -/* Not recognised. */ -/* --------------- */ -/* If the attribute is still not recognised, and the Frame has only 1 axis, - and the attribute name does not already include an axis specifier, try - again after appending "(1)" to the end of the attribute name. */ - } else if( !has_axis && astGetNaxes( this ) == 1 && equals ) { - -/* Take a copy of the supplied setting, allowing 3 extra characters for the - axis specifier "(1)". */ - axis_setting = astMalloc( len + 4 ); - if( axis_setting ) memcpy( axis_setting, setting, len ); - -/* Indicate we should free the axis_setting memory. */ - free_axis_setting = 1; - -/* Add in the axis specifier. */ - strcpy( axis_setting + ( equals - setting ), "(1)" ); - -/* Add in the equals sign and attribute value. */ - strcpy( axis_setting + ( equals - setting ) + 3, equals ); - -/* Use the new setting instead of the supplied setting. */ - old_setting = setting; - setting = axis_setting; - -/* Indicate the setting now has an axis specifier. */ - has_axis = 1; - -/* Jump back to try interpreting the new setting string. */ - goto L1; - -/* Not recognised. */ -/* --------------- */ -/* If the attribute is still not recognised, pass it on to the parent - method for further interpretation. First re-instate the original setting - string if it was changed above. */ - } else { - if( free_axis_setting ) { - setting = old_setting; - axis_setting = astFree( axis_setting ); - free_axis_setting = 0; - } - (*parent_setattrib)( this_object, setting, status ); - } - - if( free_axis_setting ) axis_setting = astFree( axis_setting ); - -/* Undefine macros local to this function. */ -#undef MATCH -} - -static void SetAxis( AstFrame *this, int axis, AstAxis *newaxis, int *status ) { -/* -*+ -* Name: -* astSetAxis - -* Purpose: -* Set a new Axis for a Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astSetAxis( AstFrame *this, int axis, AstAxis *newaxis ) - -* Class Membership: -* Frame method. - -* Description: -* This function allows a new Axis object to be associated with one -* of the axes of a Frame, 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 Frame. -* axis -* The index (zero-based) of the axis whose associated Axis object is to -* be replaced. -* newaxis -* Pointer to the new Axis object. -*- -*/ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Validate and permute the axis index supplied. */ - axis = astValidateAxis( this, axis, 1, "astSetAxis" ); - -/* If OK, annul the Frame's pointer to the old Axis object and clone a pointer - to the new one to replace it. */ - if ( astOK ) { - this->axis[ axis ] = astAnnul( this->axis[ axis ] ); - this->axis[ axis ] = astClone( newaxis ); - } -} - -static void SetFrameFlags( AstFrame *this, int flags, int *status ){ -/* -*+ -* Name: -* astSetFrameFlags - -* Purpose: -* Store a new bit mask of flags in a Frame. - -* Type: -* Protected function. - -* Synopsis: -* #include "frame.h" -* void astSetFrameFlags( astFrame *this, int flags ) - -* Class Membership: -* Frame member function. - -* Description: -* This function stores a new set of flags in a Frame. The flags can -* be retrieved using astGetFrameFlags. - -* Parameters: -* this -* The Frame. -* flags -* A bit mask holding the flags. Currently, the following bits are -* used: -* -* 0 - Used to indicate if the Frame is currently involved in an -* attempt to restore the integrity of a FrameSet following -* changes to the attribute values of the Frame. - -*- -*/ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Assign the new bit mask. */ - this->flags = flags; -} - -static void SetFrameVariants( AstFrame *this, AstFrameSet *variants, int *status ){ -/* -*+ -* Name: -* astSetFrameVariants - -* Purpose: -* Store a FrameSet holding alternative Frame properties. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astSetVariants( AstFrame *this, AstFrameSet *variants ) - -* Class Membership: -* Frame method. - -* Description: -* This function adds sets of alternative Frame properties to a Frame. - -* Parameters: -* this -* Pointer to the Frame. -* variants -* Pointer to a FrameSet in which each Frame is of the same class -* and dimensionality as "this" and all Frames have unique Domain -* names. - -* Notes: -* - A clone of the supplied FrameSet pointer is stored in the Frame. -*- -*/ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Annul any variants FrameSet already stored in the Frame. */ - if( this->variants ) this->variants = astAnnul( this->variants ); - -/* Store a clone of ht esupplied FrameSet pointer. */ - if( variants ) this->variants = astClone( variants ); - -} - -static void SetUnit( AstFrame *this, int axis, const char *unit, int *status ) { -/* -* Name: -* SetUnit - -* Purpose: -* Set a value for the Unit attribute of a Frame. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void SetUnit( AstFrame *this, int axis, const char *unit, int *status ) - -* Class Membership: -* Frame method. - -* Description: -* This function sets the Unit value for a Frame. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The number of the axis (zero-based) for which the Unit value is to -* be set. -* unit -* The new value to be set. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* void. -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - char *c; /* Copy of supplied string */ - const char *oldunit; /* Pointer to old units string */ - int l; /* Used length of supplied string */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get a copy of the supplied string which excludes trailing spaces. */ - l = astChrLen( unit ); - c = astStore( NULL, unit, (size_t) (l + 1) ); - if( astOK ) { - c[ l ] = 0; - -/* Validate the axis index and obtain a pointer to the required Axis. */ - (void) astValidateAxis( this, axis, 1, "astSetUnit" ); - ax = astGetAxis( this, axis ); - -/* The new unit may require the Label and/or Symbol to be changed, but - only if the Frames ActiveUnit flag is set. */ - if( astGetActiveUnit( this ) ) { - -/* Get the existing Axis unit, using the astGetUnit method (rather than - astGetAxisUnit) in order to get any default value in the case where - the Unit attribute is not set. */ - oldunit = astGetUnit( this, axis ); - -/* Assign the new Unit value. This modifies labels and/or Symbols if - necessary. */ - NewUnit( ax, oldunit, c, "astSetUnit", astGetClass( this ), status ); - } - -/* Set the Axis Unit attribute value. */ - astSetAxisUnit( ax, c ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - } - -/* Free the string copy */ - c = astFree( c ); - -} - -static int SubFrame( AstFrame *target, AstFrame *template, - int result_naxes, const int *target_axes, - const int *template_axes, AstMapping **map, - AstFrame **result, int *status ) { -/* -*+ -* Name: -* astSubFrame - -* Purpose: -* Select axes from a Frame and convert to the new coordinate system. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astSubFrame( AstFrame *target, AstFrame *template, -* int result_naxes, const int *target_axes, -* const int *template_axes, AstMapping **map, -* AstFrame **result ) - -* Class Membership: -* Frame method. - -* Description: -* This function selects a requested sub-set (or super-set) of the axes from -* a "target" Frame 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 target and result Frames. 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 Frame, from which 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 Frame. This number may -* be greater than or less than the number of axes in this 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 -* target Frame. 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 Frame, 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 target -* Frame 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. - -* Returned Value: -* A non-zero value is returned if coordinate conversion is -* possible between the target 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. - -* Implementation Deficiencies: -* - Any axis selection is currently permitted. Probably this -* should be restricted so that each axis can only be selected -* once. The astValidateAxisSelection method will do this but -* currently there are bugs in the CmpFrame class that cause axis -* selections which will not pass this test. Install the validation -* when these are fixed. -*- - -* Implementation Notes: -* - This implementation addresses the selection of axes from a -* Frame class object. This simply results in another object of the -* same class and a Mapping which describes an axis permutation (or -* a unit Mapping as a special case). Changes of Frame attributes -* have no significance for coordinate values in this class, so do -* not affect the Mapping returned. -*/ - -/* Local Variables: */ - AstAxis *newaxis; /* Pointer to new Axis object */ - AstFrame *tempframe; /* Pointer to temporary Frame */ - AstMapping *aumap; /* A units Mapping for a single axis */ - AstMapping *numap; /* The new total units Mapping */ - AstMapping *umap; /* The total units Mapping */ - int *inperm; /* Pointer to permutation array */ - int *outperm; /* Pointer to permutation array */ - int match; /* Coordinate conversion possible? */ - int result_axis; /* Result Frame axis index */ - int target_axis; /* Target Frame axis index */ - int target_naxes; /* Number of target Frame axes */ - int unit; /* Unit Mapping appropriate? */ - int uunit; /* Is the "umap" Mapping a UnitMap? */ - -/* Initialise the returned values. */ - *map = NULL; - *result = NULL; - match = 0; - -/* Check the global error status. */ - if ( !astOK ) return match; - -/* Obtain the number of target Frame axes. */ - target_naxes = astGetNaxes( target ); - -/* Ensure we do not attempt to use a negative number of result axes. */ - if ( result_naxes < 0 ) result_naxes = 0; - -/* Create a temporary new Frame with the required number of axes. This will - have a default Axis object associated with each of its axes. We will - replace these where necessary with copies of the actual Axis objects we - require. */ - tempframe = astFrame( result_naxes, "", status ); - -/* Allocate memory to store two permutation arrays. These will be used to - construct the Mapping that relates the target and result Frames. */ - inperm = astMalloc( sizeof( int ) * (size_t) target_naxes ); - outperm = astMalloc( sizeof( int ) * (size_t) result_naxes ); - if ( astOK ) { - -/* Initialise the array that associates each target axis with the corresponding - result axis (filling it with the value -1 initially signifies no - associations). */ - for ( target_axis = 0; target_axis < target_naxes; target_axis++ ) { - inperm[ target_axis ] = -1; - } - -/* Loop through each axis in the result Frame and obtain the index of the axis - in the target Frame from which it is to be derived. */ - for ( result_axis = 0; result_axis < result_naxes; result_axis++ ) { - target_axis = target_axes[ result_axis ]; - -/* Check if the resulting axis index is valid. If not, this result axis is not - to be derived from any target axis, and it will therefore be left with its - default attributes. Make an entry in the appropriate permutation array to - indicate that this result axis is unassociated. */ - if ( ( target_axis < 0 ) || ( target_axis >= target_naxes ) ) { - outperm[ result_axis ] = -1; - -/* Otherwise, obtain a pointer to the target Axis object and modify the - temporary Frame so that its axis is associated with the same Axis object. - Annul the Axis pointer afterwards. */ - } else { - newaxis = astGetAxis( target, target_axis ); - astSetAxis( tempframe, result_axis, newaxis ); - newaxis = astAnnul( newaxis ); - -/* Update both permutation arrays to record the association between the target - and result axes. */ - outperm[ result_axis ] = target_axis; - inperm[ target_axis ] = result_axis; - } - -/* Quit looping if an error occurs. */ - if ( !astOK ) break; - } - -/* So far, we have only modified pointers in the temporary Frame to refer to - the target Frame's Axis objects. Since we will next modify these objects' - attributes, we must make a deep copy of the entire temporary Frame so that - we do not modify the target's axes. This copy now becomes our result Frame. - Annul the temporary one. */ - if ( astOK ) { - *result = astCopy( tempframe ); - tempframe = astAnnul( tempframe ); - -/* Invoke the target "astOverlay" method to overlay any remaining - attributes from the target Frame which are not associated with - individual axes (e.g. the Frame's Title and Domain). */ - astOverlay( target, target_axes, *result ); - -/* If a template Frame was supplied, also invoke its astOverlay method to - overlay its attributes on the result Frame. (Note that in this particular - case this has no effect other than transferring attributes. In general, - however, i.e. in derived classes, this process is vital to determining the - mapping below, whose main purpose is to convert between the target and - result Frames. These will have different attributes as a result of the - influence that the template has here.) */ - if ( template ) astOverlay( template, template_axes, *result ); - -/* We will next generate the Mapping that relates the target and result - Frames. If appropriate this should be a unit Mapping (UnitMap), so test if - the number of axes in both Frames is equal. */ - unit = ( target_naxes == result_naxes ); - -/* If so, check the contents of one of the permutation arrays to see if all - result axes are associated with the corresponding target axis (the converse - then also follows). If not, note this fact and quit checking. */ - if ( unit ) { - for ( result_axis = 0; result_axis < result_naxes; - result_axis++ ) { - if ( outperm[ result_axis ] != result_axis ) { - unit = 0; - break; - } - } - } - -/* If a unit Mapping is appropriate, then construct it. */ - if ( unit ) { - *map = (AstMapping *) astUnitMap( result_naxes, "", status ); - -/* Otherwise, construct a Mapping describing the axis permutation we have - produced. */ - } else { - *map = (AstMapping *) astPermMap( target_naxes, inperm, - result_naxes, outperm, NULL, - "", status ); - } - -/* Note that coordinate conversion is possible. */ - match = 1; - -/* If the ActiveUnit flag in both template and result Frame is non-zero, we - now modify the Mapping to take account of any differences in the Units - attributes of the target and results Frames. */ - if( template && astGetActiveUnit( template ) && - astGetActiveUnit( *result ) ) { - -/* Loop round the axes of the results Frame, accumulating a parallel CmpMap - ("umap") in which each Mapping is the 1-D Mapping which transforms the - Units of the corresponding target axis into the Units of the results - axis. */ - umap = NULL; - uunit = 1; - for( result_axis = 0; result_axis < result_naxes; result_axis++ ) { - -/* Find the index of the corresponding target axis. */ - if( unit ) { - target_axis = result_axis; - } else { - target_axis = outperm[ result_axis ]; - } - -/* Get the Unit string for both axes, and attempt to find a Mapping which - transforms values in the target units into the corresponding value in the - results units. If this results axis does not have a corresponding - target axis, then indicate that no units mapping can be found. */ - if( target_axis > -1 ) { - aumap = astUnitMapper( astGetUnit( target, target_axis ), - astGetUnit( *result, result_axis ), - NULL, NULL ); - } else { - aumap = NULL; - } - -/* If no Mapping could be found, annull the Mapping and leave the loop. - Otherwise, see if the Mapping is a UnitMap. If not, set a flag to indicate - that we have at least one non-unit map. */ - if( !aumap ) { - if( umap ) umap = astAnnul( umap ); - match = 0; - break; - } else { - if( !astIsAUnitMap( aumap ) ) uunit = 0; - } - -/* Add this Mapping into the parallel CmpMap. */ - if( umap ) { - numap = (AstMapping *) astCmpMap( umap, aumap, 0, "", status ); - umap = astAnnul( umap ); - aumap = astAnnul( aumap ); - umap = numap; - } else { - umap = aumap; - } - } - -/* If the resulting CmpMap is not just a UnitMap, add it in series with - the current results mapping, and then simplify it. */ - if( !uunit && umap ) { - numap = (AstMapping *) astCmpMap( *map, umap, 1, "", status ); - (void) astAnnul( *map ); - *map = numap; - } - -/* Annul the CmpMap containing the units Mappings. */ - if( umap ) umap = astAnnul( umap ); - -/* If the units could not bve matched annul the returned mapping. */ - if( !match && *map ) *map = astAnnul( *map ); - } - } - } - -/* Free the memory used for the permutation arrays. */ - inperm = astFree( inperm ); - outperm = astFree( outperm ); - -/* If an error occurred, annul the returned objects and reset the returned - value. */ - if ( !astOK ) { - *map = astAnnul( *map ); - *result = astAnnul( *result ); - match = 0; - } - -/* Return the result. */ - return match; -} - -static AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) { -/* -*+ -* Name: -* astSystemCode - -* Purpose: -* Convert a string into a coordinate system type code. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* AstSystemType SystemCode( AstFrame *this, const char *system ) - -* Class Membership: -* Frame method. - -* 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. - -* 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 */ - -/* Initialise. */ - result = AST__BADSYSTEM; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Match the "system" string against each possibility and assign the - result. The basic Frame class only supports a single system - "Cartesian". */ - if ( astChrMatch( "Cartesian", system ) ) { - result = AST__CART; - } - -/* Return the result. */ - return result; -} - -static const char *SystemString( AstFrame *this, AstSystemType system, int *status ) { -/* -*+ -* Name: -* astSystemString - -* Purpose: -* Convert a coordinate system type code into a string. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* const char *astSystemString( AstFrame *this, AstSystemType system ) - -* Class Membership: -* Frame method. - -* 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. - -* 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: */ - const char *result; /* Pointer value to return */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Match the "system" value against each possibility and convert to a - string pointer. (Where possible, return the same string as would be - used in the FITS WCS representation of the coordinate system). A basic - Frame only allows a single System value, "Cartesian". */ - switch ( system ) { - case AST__CART: - result = "Cartesian"; - break; - } - -/* Return the result pointer. */ - return result; - -} - -static int TestActiveUnit( AstFrame *this, int *status ){ -/* -*+ -* Name: -* astTestActiveUnit - -* Purpose: -* Determines if the ActiveUnit flag is set. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astTestActiveUnit( AstFrame *this ) - -* Class Membership: -* Frame method. - -* Description: -* This function tests the current value of the ActiveUnit flag for a -* Frame. See the description of the astSetActiveUnit function for a -* description of the ActiveUnit flag. - -* Parameters: -* this -* Pointer to the Frame. - -* Returned Value: -* Non-zero if the flag has been set. Zero otherwise. - -* Notes: -* - A zero 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: */ - int result; /* The returned value */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Return the result. */ - return ( this->active_unit != -INT_MAX ); -} - -static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { -/* -* Name: -* TestAttrib - -* Purpose: -* Test if a specified attribute value is set for a Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* int TestAttrib( AstObject *this, const char *attrib, int *status ) - -* Class Membership: -* Frame member function (over-rides the astTestAttrib protected -* method inherited from the Mapping class). - -* Description: -* This function returns a boolean result (0 or 1) to indicate whether -* a value has been set for one of a Frame's attributes. - -* Parameters: -* this -* Pointer to the Frame. -* 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: -* - This function uses one-based axis numbering so that it is -* suitable for external (public) use. -* - 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: */ - AstAxis *ax; /* Pointer to Axis */ - AstFrame *pfrm; /* Pointer to primary Frame containing axis */ - AstFrame *this; /* Pointer to the Frame structure */ - char pfrm_attrib[ 100 ]; /* Primary Frame attribute */ - char *axis_attrib; /* Pointer to axis attribute name */ - const char *old_attrib; /* Pointer to supplied attribute name string */ - int axis; /* Frame axis number */ - int axis_nc; /* No. characters in axis attribute name */ - int free_axis_attrib; /* Should axis_attrib be freed? */ - int has_axis; /* Does attrib name include axis specifier? */ - int len; /* Length of attrib string */ - int nc; /* No. characters read by astSscanf */ - int oldrep; /* Original error reporting state */ - int paxis; /* Axis index within primary frame */ - int result; /* Result value to return */ - int used; /* Could the setting string be used? */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_object; - -/* Set a flag indicating if the attribute name includes an axis - specifier. */ - has_axis = ( strchr( attrib, '(' ) != NULL ); - -/* A flag indicating that we do not need to free the axis_attrib memory. */ - free_axis_attrib = 0; - -/* Initialise things to avoid compiler warnings. */ - axis_attrib = NULL; - old_attrib = NULL; - -/* Jump back to here if we are trying the same attribute but with an explicit - axis "(1)" added to the end of the name. */ -L1: - -/* Obtain the length of the attrib string. */ - len = strlen( attrib ); - -/* Check the attribute name and test the appropriate attribute. */ - -/* Digits. */ -/* ------- */ - if ( !strcmp( attrib, "digits" ) ) { - result = astTestDigits( this ); - -/* Digits(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "digits(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - -/* There is no function to test the Digits attribute for an axis - directly, so obtain a pointer to the Axis and use this to test the - attribute. */ - (void) astValidateAxis( this, axis - 1, 1, "astTestDigits(axis)" ); - ax = astGetAxis( this, axis - 1 ); - result = astTestAxisDigits( ax ); - ax = astAnnul( ax ); - -/* Direction(axis). */ -/* ---------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "direction(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astTestDirection( this, axis - 1 ); - -/* Epoch. */ -/* ------ */ - } else if ( !strcmp( attrib, "epoch" ) ) { - result = astTestEpoch( this ); - -/* Bottom(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "bottom(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astTestBottom( this, axis - 1 ); - -/* Top(axis). */ -/* ---------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "top(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astTestTop( this, axis - 1 ); - -/* Domain. */ -/* ------- */ - } else if ( !strcmp( attrib, "domain" ) ) { - result = astTestDomain( this ); - -/* Format(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "format(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astTestFormat( this, axis - 1 ); - -/* Label(axis). */ -/* ------------ */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "label(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astTestLabel( this, axis - 1 ); - -/* MatchEnd. */ -/* --------- */ - } else if ( !strcmp( attrib, "matchend" ) ) { - result = astTestMatchEnd( this ); - -/* MaxAxes. */ -/* -------- */ - } else if ( !strcmp( attrib, "maxaxes" ) ) { - result = astTestMaxAxes( this ); - -/* MinAxes. */ -/* -------- */ - } else if ( !strcmp( attrib, "minaxes" ) ) { - result = astTestMinAxes( this ); - -/* Permute. */ -/* -------- */ - } else if ( !strcmp( attrib, "permute" ) ) { - result = astTestPermute( this ); - -/* PreserveAxes. */ -/* ------------- */ - } else if ( !strcmp( attrib, "preserveaxes" ) ) { - result = astTestPreserveAxes( this ); - -/* Symbol(axis). */ -/* ------------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "symbol(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astTestSymbol( this, axis - 1 ); - -/* AlignSystem. */ -/* ------------ */ - } else if ( !strcmp( attrib, "alignsystem" ) ) { - result = astTestAlignSystem( this ); - -/* System. */ -/* ------- */ - } else if ( !strcmp( attrib, "system" ) ) { - result = astTestSystem( this ); - -/* Title. */ -/* ------ */ - } else if ( !strcmp( attrib, "title" ) ) { - result = astTestTitle( this ); - -/* Unit(axis). */ -/* ----------- */ - } else if ( nc = 0, - ( 1 == astSscanf( attrib, "unit(%d)%n", &axis, &nc ) ) - && ( nc >= len ) ) { - result = astTestUnit( this, axis - 1 ); - -/* ObsLat. */ -/* ------- */ - } else if ( !strcmp( attrib, "obslat" ) ) { - result = astTestObsLat( this ); - -/* ObsLon. */ -/* ------- */ - } else if ( !strcmp( attrib, "obslon" ) ) { - result = astTestObsLon( this ); - -/* ObsAlt. */ -/* ------- */ - } else if ( !strcmp( attrib, "obsalt" ) ) { - result = astTestObsAlt( this ); - -/* Dtai. */ -/* ---- */ - } else if ( !strcmp( attrib, "dtai" ) ) { - result = astTestDtai( this ); - -/* Dut1. */ -/* ---- */ - } else if ( !strcmp( attrib, "dut1" ) ) { - result = astTestDut1( this ); - -/* Read-only attributes. */ -/* --------------------- */ -/* Test if the attribute name matches any of the read-only attributes - of this class. If it does, then return zero. */ - } else if ( !strcmp( attrib, "naxes" ) || - !strncmp( attrib, "normunit", 8 ) || - !strncmp( attrib, "internalunit", 12 ) ) { - result = 0; - -/* Other axis attributes. */ -/* ---------------------- */ -/* If the attribute was not identified above, but appears to refer to - a Frame axis, then it may refer to an Axis object of a derived type - (which has additional attributes not recognised here). */ - } else if ( !free_axis_attrib && ( nc = 0, - ( 1 == astSscanf( attrib, "%*[^()]%n(%d)%n", - &axis_nc, &axis, &nc ) ) - && ( nc >= len ) ) ) { - -/* Validate the axis index and extract the attribute name. */ - (void) astValidateAxis( this, axis - 1, 1, "astTest" ); - axis_attrib = astString( attrib, axis_nc ); - -/* Obtain a pointer to the Axis object. */ - ax = astGetAxis( this, axis - 1 ); - if( astOK ) { - -/* Assume that we will be able to use the attribute name. */ - used = 1; - -/* Temporarily switch off error reporting so that if the following attempt - to access the axis attribute fails, we can try to interpret the - attribute name as an attribute of the primary Frame containing the - specified axis. Any errors reported in this context will simply be - ignored, in particularly they are not deferred for later delivery. */ - oldrep = astReporting( 0 ); - -/* Use the Axis astTestAttrib method to test the attribute value. */ - result = astTestAttrib( ax, axis_attrib ); - -/* If the above call failed with a status of AST__BADAT, indicating that - the attribute name was not recognised, clear the status so that we can - try to interpret the attribute name as an attribute of the primary Frame - containing the specified axis. */ - if( astStatus == AST__BADAT ) { - astClearStatus; - -/* Find the primary Frame containing the specified axis. */ - astPrimaryFrame( this, axis - 1, &pfrm, &paxis ); - -/* Only attempt to use the primary Frame if it is not the same as "this" - - otherwise we could end up in an infinite loop. */ - if( pfrm != this ) { - -/* astPrimaryFrame returns the original - unpermuted - axis index within - the primary Frame. So we need to take into account any axis permutation - which has been applied to the primary Frame when forming the attribute name - to use below. Find the permuted (external) axis index which corresponds to - the internal (unpermuted) axis index "paxis". */ - paxis = astValidateAxis( pfrm, paxis, 0, "astTest" ); - -/* Modify the attribute name to refer to the axis numbering of the - primary frame. */ - sprintf( pfrm_attrib, "%s(%d)", axis_attrib, paxis + 1 ); - -/* Attempt to test the attribute as an attribute of the primary Frame. */ - result = astTestAttrib( pfrm, pfrm_attrib ); - -/* If this failed, clear the status and indicate that we have not managed to - use the attribute name. */ - if( !astOK ) { - astClearStatus; - used = 0; - } - - } else { - used = 0; - } - -/* If not found attempt to test the attribute value in the Axis, omitting - the axis index. */ - if( ! used ) { - result = astTestAttrib( pfrm, axis_attrib ); - if( !astOK ) { - astClearStatus; - } else { - used = 1; - } - } - -/* Annul the primary Frame pointer. */ - pfrm = astAnnul( pfrm ); - } - -/* Re-instate the original error reporting state. */ - astReporting( oldrep ); - -/* If we could not use the attribute name, attempt to test the axis - attribute again, this time retaining the error report. This is done - to ensure the user gets an appropriate error message. */ - if( !used ) result = astTestAttrib( ax, axis_attrib ); - } - -/* Annul the Axis pointer and free the memory holding the attribute - name. */ - ax = astAnnul( ax ); - axis_attrib = astFree( axis_attrib ); - -/* Not recognised. */ -/* --------------- */ -/* If the attribute is still not recognised, and the Frame has only 1 axis, - and the attribute name does not already include an axis specifier, try - again after appending "(1)" to the end of the attribute name. */ - } else if( !has_axis && astGetNaxes( this ) == 1 ) { - -/* Take a copy of the supplied name, allowing 3 extra characters for the - axis specifier "(1)". */ - axis_attrib = astMalloc( len + 4 ); - if( axis_attrib ) memcpy( axis_attrib, attrib, len ); - -/* Indicate we should free the axis_attrib memory. */ - free_axis_attrib = 1; - -/* Add in the axis specifier. */ - strcpy( axis_attrib + len, "(1)" ); - -/* Use the new attribute name instead of the supplied name. */ - old_attrib = attrib; - attrib = axis_attrib; - -/* Indicate the attribute name now has an axis specifier. */ - has_axis = 1; - -/* Jump back to try interpreting the new attribute name. */ - goto L1; - -/* Not recognised. */ -/* --------------- */ -/* If the attribute name is still not recognised, pass it on to the parent - method for further interpretation. First re-instate the original attrib - name string if it was changed above. */ - } else { - if( free_axis_attrib ) { - attrib = old_attrib; - axis_attrib = astFree( axis_attrib ); - } - result = (*parent_testattrib)( this_object, attrib, status ); - } - -/* Return the result, */ - return result; -} - -static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, - int forward, AstPointSet *out, int *status ) { -/* -* Name: -* Transform - -* Purpose: -* Use a Frame to transform a set of points. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* AstPointSet *Transform( AstMapping *this, AstPointSet *in, -* int forward, AstPointSet *out, int *status ) - -* Class Membership: -* Frame member function (over-rides the astTransform method inherited -* from the Mapping class). - -* Description: -* This function takes a Frame and a set of points encapsulated in a -* PointSet and transforms the points so as to perform the identity -* transformation (i.e. simply copies the coordinate values). - -* Parameters: -* this -* Pointer to the Frame. -* 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. In this case, both transformations are equivalent. -* 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. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Pointer to the output (possibly new) 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. -* - The number of coordinate values per point in the input PointSet must -* match the number of coordinates for the Frame being applied. This number -* will be equal to the number of Frame axes. -* - If an output PointSet is supplied, it must have space for sufficient -* number of points and coordinate values per point to accommodate the -* result. Any excess space will be ignored. -*/ - -/* Local Variables: */ - AstFrame *this; /* Pointer to the Frame structure */ - AstPointSet *result; /* Pointer value to be returned */ - AstUnitMap *unitmap; /* Pointer to temporary UnitMap */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_mapping; - -/* Create a unit Mapping with one coordinate for each Frame axis. */ - unitmap = astUnitMap( astGetNaxes( this ), "", status ); - -/* Use the Mapping to transform (i.e. copy) the coordinate values. */ - result = astTransform( unitmap, in, forward, out ); - -/* Annul the Mapping. */ - unitmap = astAnnul( unitmap ); - -/* If an error occurred and a new PointSet may have been created, then annul - the result. In any case, ensure that a NULL pointer is returned. */ - if ( !astOK ) { - if ( !out ) result = astAnnul( result ); - result = NULL; - } - -/* Return the result pointer. */ - return result; -} - -static int Unformat( AstFrame *this, int axis, const char *string, - double *value, int *status ) { -/* -*+ -* Name: -* astUnformat - -* Purpose: -* Read a formatted coordinate value for a Frame axis. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astUnformat( AstFrame *this, int axis, const char *string, -* double *value ) - -* Class Membership: -* Frame method. - -* Description: -* This function reads a formatted coordinate value for a Frame -* 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 Frame. -* axis -* The number of the Frame 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. - -* 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. -*- - -* Implementation Notes: -* - This function implements the basic astUnformat method -* available via the protected interface to the Frame class. The -* public interface to this method is provided by the -* astUnformatId_ function. -*/ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis object */ - const char *label; /* Pointer to axis label string */ - double coord; /* Coordinate value read */ - int digits_set; /* Axis Digits attribute set? */ - int nc; /* Number of characters read */ - int status_value; /* AST error status */ - -/* Initialise. */ - nc = 0; - -/* Check the global error status. */ - if ( !astOK ) return nc; - -/* Validate the axis index and obtain a pointer to the required Axis. */ - (void) astValidateAxis( this, axis, 1, "astUnformat" ); - ax = astGetAxis( this, axis ); - -/* Test if any Axis attributes which may affect the result are - undefined (i.e. have not been explicitly set). If so, we over-ride - them, giving them temporary values dictated by the Frame. Only the - Digits attribute is potentially relevant here. */ - digits_set = astTestAxisDigits( ax ); - if ( !digits_set ) astSetAxisDigits( ax, astGetDigits( this ) ); - -/* Read the coordinate value. */ - if ( astOK ) { - nc = astAxisUnformat( ax, string, &coord ); - -/* If an error occurred, save and temporarily clear the global error - status while the axis Label string is obtained. Then restore the - original error status value afterwards. */ - if ( !astOK ) { - status_value = astStatus; - astClearStatus; - label = astGetLabel( this, axis ); - astSetStatus( status_value ); - -/* Report a contextual error message containing the axis label. */ - astError( status_value, "%s(%s): Unable to read \"%s\" value.", status, - "astUnformat", astGetClass( this ), label ); - } - } - -/* Clear any Axis attributes that were temporarily over-ridden. */ - if ( !digits_set ) astClearAxisDigits( ax ); - -/* Annul the Axis pointer. */ - ax = astAnnul( ax ); - -/* If an error occurred, clear the count 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, int axis, int fwd, const char *method, - int *status ) { -/* -*+ -* Name: -* astValidateAxis - -* Purpose: -* Validate and permute a Frame's axis index. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astValidateAxis( AstFrame *this, int axis, int fwd, -* const char *method ) - -* Class Membership: -* Frame method. - -* Description: -* This function checks the validity of an index (zero-based) which -* is to be used to address one of the coordinate axes of a -* Frame. If the index is valid, it is permuted using the axis -* permutation array associated with the Frame and the (zero-based) -* permuted axis index is returned. This gives the location of the -* required axis information within the Frame's internal arrays. If -* the axis index supplied is not valid, an error is reported and -* the global error status is set. - -* Parameters: -* this -* Pointer to the Frame. -* 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 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. - -* 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. -* - Error messages issued by this function refer to the public -* numbering system used for axes which is one-based (zero-based axis -* indices are used internally). -*- -*/ - -/* Local Variables: */ - const int *perm; /* Pointer to axis permutation array */ - int naxes; /* Number of Frame axes */ - int result; /* Permuted axis index */ - -/* Initialise. */ - result = 0; - -/* Determine the number of Frame axes. */ - naxes = astGetNaxes( this ); - if ( astOK ) { - -/* If the Frame has no axes, report an error (note we convert to - one-based axis numbering in the error message). */ - 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, use one-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 the axis permutation array and - use this to generate the permuted axis value. */ - } else { - perm = astGetPerm( this ); - if( perm ) { - -/* External to internal is a simple look-up. */ - if( fwd ) { - result = perm[ axis ]; - -/* Internal to external requires a search through the permutation array. */ - } else { - for( result = 0; result < naxes; result++ ) { - if( perm[ result ] == axis ) break; - } - } - } - } - } - -/* Return the result. */ - return result; -} - -static void ValidateAxisSelection( AstFrame *this, int naxes, const int *axes, - const char *method, int *status ) { -/* -*+ -* Name: -* astValidateAxisSelection - -* Purpose: -* Check that a set of axes selected from a Frame is valid. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* void astValidateAxisSelection( AstFrame *this, int naxes, -* const int *axes, const char *method ) - -* Class Membership: -* Frame method. - -* 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. -*- -*/ - -/* Local Variables: */ - int *count; /* Pointer to temporary array of counts */ - int axis; /* Loop counter for selected axes */ - int frame_axis; /* Loop counter for Frame axes */ - int frame_naxes; /* Number of Frame axes */ - int valid; /* Axis selection valid? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Check to see if no axes have been selected. If so, there is nothing to - do. */ - if ( naxes ) { - -/* Initialise. */ - valid = 1; - -/* Obtain the number of Frame axes and allocate an array of int with - one element for each Frame axis. This will store a count of the - number of times each axis is selected. */ - frame_naxes = astGetNaxes( this ); - count = astMalloc( sizeof( int ) * (size_t) frame_naxes ); - if ( astOK ) { - -/* Initialise the array of counts to zero. */ - for ( frame_axis = 0; frame_axis < frame_naxes; frame_axis++ ) { - count[ frame_axis ] = 0; - } - -/* Loop through each selected axis. */ - for ( axis = 0; axis < naxes; axis++ ) { - frame_axis = axes[ axis ]; - -/* Check if the selected axis index is valid for the Frame. If so, increment - the selection count for that Frame axis. */ - if ( ( frame_axis >= 0 ) && ( frame_axis < frame_naxes ) ) { - count[ frame_axis ]++; - } - } - -/* Loop through the count array and check that no Frame axis was selected - more than once. If it was, clear the "valid" flag and quit checking. */ - for ( frame_axis = 0; frame_axis < frame_naxes; frame_axis++ ) { - if ( count[ frame_axis ] > 1 ) { - valid = 0; - break; - } - } - } - -/* Free the temporary count array. */ - count = astFree( count ); - -/* If no error has occurred, but the axis selection is not valid, then report - an error. */ - if ( astOK && !valid ) { - astError( AST__SELIN, "%s(%s): Invalid axis selection - each axis " - "may be selected only once.", status, method, astGetClass( this ) ); - } - } -} - -static int ValidateSystem( AstFrame *this, AstSystemType system, const char *method, int *status ) { -/* -*+ -* Name: -* astValidateSystem - -* Purpose: -* Validate a value for a Frame's System attribute. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frame.h" -* int astValidateSystem( AstFrame *this, AstSystemType system, -* const char *method ) - -* Class Membership: -* Frame method. - -* 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. - -* 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 */ - -/* Initialise. */ - result = AST__BADSYSTEM; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* If the value is out of bounds, report an error. */ - if ( system < FIRST_SYSTEM || system > LAST_SYSTEM ) { - astError( AST__AXIIN, "%s(%s): Bad value (%d) given for the System " - "or AlignSystem attribute of a %s.", status, method, - astGetClass( this ), (int) system, astGetClass( this ) ); - -/* Otherwise, return the supplied value. */ - } else { - result = system; - } - -/* Return the result. */ - return result; -} - -/* Functions which access class attributes. */ -/* ---------------------------------------- */ -/* Implement member functions to access the attributes associated with - the axes of a Frame using the private macros defined for this - purpose at the start of this file. */ - -/* -*att++ -* Name: -* Naxes - -* Purpose: -* Number of Frame axes. - -* Type: -* Public attribute. - -* Synopsis: -* Integer, read-only. - -* Description: -* This is a read-only attribute giving the number of axes in a -* Frame (i.e. the number of dimensions of the coordinate space -* which the Frame describes). This value is determined when the -* Frame is created. - -* Applicability: -* Frame -* All Frames have this attribute. -* FrameSet -* The Naxes attribute of a FrameSet is the same as that of its -* current Frame (as specified by the Current attribute). -* CmpFrame -* The Naxes attribute of a CmpFrame is equal to the sum of the -* Naxes values of its two component Frames. -*att-- -*/ - - -/* -*att++ -* Name: -* Direction(axis) - -* Purpose: -* Display axis in conventional direction? - -* Type: -* Public attribute. - -* Synopsis: -* Integer (boolean). - -* Description: -* This attribute is a boolean value which suggests how the axes of -* a Frame should be displayed (e.g.) in graphical output. By -* default, it has the value one, indicating that they should be -* shown in the conventional sense (increasing left to right for an -* abscissa, and bottom to top for an ordinate). If set to zero, -* this attribute indicates that the direction should be reversed, -* as would often be done for an astronomical magnitude or a right -* ascension axis. - -* Applicability: -* Frame -* The default Direction value supplied by the Frame class is 1, -* indicating that all axes should be displayed in the -* conventional direction. -* SkyFrame -* The SkyFrame class re-defines the default Direction value to -* suggest that certain axes (e.g. right ascension) should be -* plotted in reverse when appropriate. -* FrameSet -* The Direction attribute of a FrameSet axis is the same as -* that of its current Frame (as specified by the Current -* attribute). -* Plot -* The Direction attribute of the base Frame in a Plot is set to -* indicate the sense of the two graphics axes, as implied by the -* graphics bounding box supplied when the Plot was created. - -* Notes: -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -* - The Direction attribute does not directly affect the behaviour -* of the AST library. Instead, it serves as a hint to applications -* programs about the orientation in which they may wish to display -* any data associated with the Frame. Applications are free to -* ignore this hint if they wish. -*att-- -*/ -/* This simply provides an interface to the Axis methods for accessing - the Direction flag. */ -MAKE_CLEAR(Direction) -MAKE_GET(Direction,int,0,0,0) -MAKE_SET(Direction,int) -MAKE_TEST(Direction) - -/* -*att++ -* Name: -* Dtai - -* Purpose: -* The TAI-UTC correction. - -* Type: -* Public attribute. - -* Synopsis: -* Floating point. - -* Description: -* This attribute specifies the difference between TAI and UTC (i.e. -* the number of leap seconds) at the moment corresponding to the -* Frame's Epoch value. The default value of AST__BAD causes the -* number of leap seconds to be determined from an internal look-up -* table, which is kept up-to-date manually by the AST development team. -* Therefore it is only necessary to assign a value to this attribute -* if the version of AST in use is so old that it does not include all -* leap seconds that occurred prior to the time represented by the -* Frame's Epoch value. - -* Applicability: -* Frame -* All Frames have this attribute. - -*att-- -*/ -/* The TAI-UTC correction, in seconds. Has a value of AST__BAD when not set. */ -astMAKE_CLEAR(Frame,Dtai,dtai,AST__BAD) -astMAKE_GET(Frame,Dtai,double,AST__BAD,(this->dtai)) -astMAKE_SET(Frame,Dtai,double,dtai,value) -astMAKE_TEST(Frame,Dtai,( this->dtai != AST__BAD )) - -/* -*att++ -* Name: -* Dut1 - -* Purpose: -* The UT1-UTC correction. - -* Type: -* Public attribute. - -* Synopsis: -* Floating point. - -* Description: -* This attribute is used when calculating the Local Apparent Sidereal -* Time corresponding to SkyFrame's Epoch value (used when converting -* positions to or from the "AzEl" system). It should be set to the -* difference, in seconds, between the UT1 and UTC timescales at the -* moment in time represented by the SkyFrame's Epoch attribute. The -* value to use is unpredictable and depends on changes in the earth's -* rotation speed. Values for UT1-UTC can be obtained from the -* International Earth Rotation and Reference Systems Service -* (IERS) at http://www.iers.org/. -* -* Currently, the correction is always less than 1 second. This is -* ensured by the occasional introduction of leap seconds into the UTC -* timescale. Therefore no great error will usually result if no value -* is assigned to this attribute (in which case a default value of -* zero is used). However, it is possible that a decision may be taken -* at some time in the future to abandon the introduction of leap -* seconds, in which case the DUT correction could grow to significant -* sizes. - -* Applicability: -* Frame -* All Frames have this attribute. - -*att-- -*/ -/* The UT1-UTC correction, in seconds. Has a value of AST__BAD when not set - yielding a default value of 0.0. */ -astMAKE_CLEAR(Frame,Dut1,dut1,AST__BAD) -astMAKE_GET(Frame,Dut1,double,0.0,(this->dut1 == AST__BAD ? 0.0 : this->dut1)) -astMAKE_SET(Frame,Dut1,double,dut1,value) -astMAKE_TEST(Frame,Dut1,( this->dut1 != AST__BAD )) - - - -/* -*att++ -* Name: -* Epoch - -* Purpose: -* Epoch of observation. - -* Type: -* Public attribute. - -* Synopsis: -* Floating point. - -* Description: -* This attribute is used to qualify the coordinate systems described by -* a Frame, by giving the moment in time when the coordinates are known -* to be correct. Often, this will be the date of observation, and is -* important in cases where coordinates systems move with respect to each -* other over the course of time. -* -* The Epoch attribute is stored as a Modified Julian Date, but -* when setting its value it may be given in a variety of -* formats. See the "Input Formats" section (below) for details. -* Strictly, the Epoch value should be supplied in the TDB timescale, -* but for some purposes (for instance, for converting sky positions -* between different types of equatorial system) the timescale is not -* significant, and UTC may be used. - -* Input Formats: -* The formats accepted when setting an Epoch value are listed -* below. They are all case-insensitive and are generally tolerant -* of extra white space and alternative field delimiters: -* -* - Besselian Epoch: Expressed in decimal years, with or without -* decimal places ("B1950" or "B1976.13" for example). -* -* - Julian Epoch: Expressed in decimal years, with or without -* decimal places ("J2000" or "J2100.9" for example). -* -* - Year: Decimal years, with or without decimal places ("1996.8" -* for example). Such values are interpreted as a Besselian epoch -* (see above) if less than 1984.0 and as a Julian epoch otherwise. -* -* - Julian Date: With or without decimal places ("JD 2454321.9" for -* example). -* -* - Modified Julian Date: With or without decimal places -* ("MJD 54321.4" for example). -* -* - Gregorian Calendar Date: With the month expressed either as an -* integer or a 3-character abbreviation, and with optional decimal -* places to represent a fraction of a day ("1996-10-2" or -* "1996-Oct-2.6" for example). If no fractional part of a day is -* given, the time refers to the start of the day (zero hours). -* -* - Gregorian Date and Time: Any calendar date (as above) but with -* a fraction of a day expressed as hours, minutes and seconds -* ("1996-Oct-2 12:13:56.985" for example). The date and time can be -* separated by a space or by a "T" (as used by ISO8601 format). - -* Output Format: -* When enquiring Epoch values, the format used is the "Year" -* format described under "Input Formats". This is a value in -* decimal years which will be a Besselian epoch if less than -* 1984.0 and a Julian epoch otherwise. By omitting any character -* prefix, this format allows the Epoch value to be obtained as -* either a character string or a floating point value. - -* Applicability: -* Frame -* All Frames have this attribute. The basic Frame class provides -* a default of J2000.0 (Julian) but makes no use of the Epoch value. -* This is because the Frame class does not distinguish between -* different Cartesian coordinate systems (see the System attribute). -* CmpFrame -* The default Epoch value for a CmpFrame is selected as follows; -* if the Epoch attribute has been set in the first component Frame -* then the Epoch value from the first component Frame is used as -* the default for the CmpFrame. Otherwise, if the Epoch attribute has -* been set in the second component Frame then the Epoch value from the -* second component Frame is used as the default for the CmpFrame. -* Otherwise, the default Epoch value from the first component -* Frame is used as the default for the CmpFrame. When the Epoch -* attribute of a CmpFrame is set or cleared, it is also set or -* cleared in the two component Frames. -* FrameSet -* The Epoch attribute of a FrameSet is the same as that of its current -* Frame (as specified by the Current attribute). -* SkyFrame -* The coordinates of sources within a SkyFrame can change with time -* for various reasons, including: (i) changing aberration of light -* caused by the observer's velocity (e.g. due to the Earth's motion -* around the Sun), (ii) changing gravitational deflection by the Sun -* due to changes in the observer's position with time, (iii) fictitious -* motion due to rotation of non-inertial coordinate systems (e.g. the -* old FK4 system), and (iv) proper motion of the source itself (although -* this last effect is not handled by the SkyFrame class because it -* affects individual sources rather than the coordinate system as -* a whole). -* -* The default Epoch value in a SkyFrame is B1950.0 (Besselian) for the -* old FK4-based coordinate systems (see the System attribute) and -* J2000.0 (Julian) for all others. -* -* Care must be taken to distinguish the Epoch value, which relates to -* motion (or apparent motion) of the source, from the superficially -* similar Equinox value. The latter is used to qualify a coordinate -* system which is itself in motion in a (notionally) predictable way -* as a result of being referred to a slowly moving reference plane -* (e.g. the equator). -* -* See the description of the System attribute for details of which -* qualifying attributes apply to each celestial coordinate system. -* TimeFrame -* A TimeFrame describes a general time axis and so cannot be completely -* characterised by a single Epoch value. For this reason the TimeFrame -* class makes no use of the Epoch attribute. However, user code can -* still make use of the attribute if necessary to represent a "typical" -* time spanned by the TimeFrame. The default Epoch value for a TimeFrame -* will be the TDB equivalent of the current value of the TimeFrame's -* TimeOrigin attribute. If no value has been set for TimeOrigin, -* then the default Epoch value is J2000.0. -*att-- -*/ -/* Clear the Epoch value by setting it to AST__BAD. */ -astMAKE_CLEAR(Frame,Epoch,epoch,AST__BAD) - -/* Provide a default value of J2000.0 setting. */ -astMAKE_GET(Frame,Epoch,double,AST__BAD,( - ( this->epoch != AST__BAD ) ? this->epoch : palEpj2d( 2000.0 ))) - -/* Allow any Epoch value to be set. */ -astMAKE_SET(Frame,Epoch,double,epoch,value) - -/* An Epoch value is set if it is not equal to AST__BAD. */ -astMAKE_TEST(Frame,Epoch,( this->epoch != AST__BAD )) - -/* -*att++ -* Name: -* Top(axis) - -* Purpose: -* Highest axis value to display - -* Type: -* Public attribute. - -* Synopsis: -* Floating point. - -* Description: -* This attribute gives the highest axis value to be displayed (for -c instance, by the astGrid method). -f instance, by the AST_GRID method). - -* Applicability: -* Frame -* The default supplied by the Frame class is to display all axis -* values, without any limit. -* SkyFrame -* The SkyFrame class re-defines the default Top value to +90 degrees -* for latitude axes, and 180 degrees for co-latitude axes. The -* default for longitude axes is to display all axis values. - -* Notes: -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -*att-- -*/ -/* This simply provides an interface to the Axis methods for accessing - the Top value. */ -MAKE_CLEAR(Top) -MAKE_GET(Top,double,DBL_MAX,0,DBL_MAX) -MAKE_SET(Top,double) -MAKE_TEST(Top) - -/* -*att++ -* Name: -* Bottom(axis) - -* Purpose: -* Lowest axis value to display - -* Type: -* Public attribute. - -* Synopsis: -* Floating point. - -* Description: -* This attribute gives the lowest axis value to be displayed (for -c instance, by the astGrid method). -f instance, by the AST_GRID method). - -* Applicability: -* Frame -* The default supplied by the Frame class is to display all axis -* values, without any limit. -* SkyFrame -* The SkyFrame class re-defines the default Bottom value to -90 degrees -* for latitude axes, and 0 degrees for co-latitude axes. The -* default for longitude axes is to display all axis values. - -* Notes: -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -*att-- -*/ -/* This simply provides an interface to the Axis methods for accessing - the Bottom value. */ -MAKE_CLEAR(Bottom) -MAKE_GET(Bottom,double,-DBL_MAX,0,-DBL_MAX) -MAKE_SET(Bottom,double) -MAKE_TEST(Bottom) - -/* -*att++ -* Name: -* Format(axis) - -* Purpose: -* Format specification for axis values. - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute specifies the format to be used when displaying -* coordinate values associated with a particular Frame axis -* (i.e. to convert values from binary to character form). It is -c interpreted by the astFormat function and determines the -f interpreted by the AST_FORMAT function and determines the -* formatting which it applies. -* -* If no Format value is set for a Frame axis, a default value is -* supplied instead. This is based on the value of the Digits, or -* Digits(axis), attribute and is chosen so that it displays the -* requested number of digits of precision. - -* Applicability: -* Frame -* The Frame class interprets this attribute as a format -* specification string to be passed to the C "printf" function -* (e.g. "%1.7G") in order to format a single coordinate value -* (supplied as a double precision number). -c -c When supplying a value for this attribute, beware that the -c "%" character may be interpreted directly as a format -c specification by some printf-like functions (such as -c astSet). You may need to double it (i.e. use "%%") to avoid -c this. -* SkyFrame -* The SkyFrame class re-defines the syntax and default value of -* the Format string to allow the formatting of sexagesimal -* values as appropriate for the particular celestial coordinate -* system being represented. The syntax of SkyFrame Format -* strings is described (below) in the "SkyFrame Formats" -* section. -* FrameSet -* The Format attribute of a FrameSet axis is the same as that -* of its current Frame (as specified by the Current -* attribute). Note that the syntax of the Format string is also -* determined by the current Frame. -* TimeFrame -* The TimeFrame class extends the syntax of the Format string to -* allow the formatting of TimeFrame axis values as Gregorian calendar -* dates and times. The syntax of TimeFrame Format strings is described -* (below) in the "TimeFrame Formats" section. - -* SkyFrame Formats: -* The Format string supplied for a SkyFrame should contain zero or -* more of the following characters. These may occur in any order, -* but the following is recommended for clarity: -* -* - "+": Indicates that a plus sign should be prefixed to positive -* values. By default, no plus sign is used. -* -* - "z": Indicates that leading zeros should be prefixed to the -* value so that the first field is of constant width, as would be -* required in a fixed-width table (leading zeros are always -* prefixed to any fields that follow). By default, no leading -* zeros are added. -* -* - "i": Use the standard ISO field separator (a colon) between -* fields. This is the default behaviour. -* -* - "b": Use a blank to separate fields. -* -* - "l": Use a letter ("h"/"d", "m" or "s" as appropriate) to -* separate fields. -* -* - "g": Use a letter and symbols to separate fields ("h"/"d", "m" or "s", -* etc, as appropriate), but include escape sequences in the formatted -* value so that the Plot class will draw the separators as small -* super-scripts. -c The default escape sequences are optimised for the pgplot graphics -c package, but new escape sequences may be specified using function -c astSetSkyDelim. -* -* - "d": Include a degrees field. Expressing the angle purely in -* degrees is also the default if none of "h", "m", "s" or "t" are -* given. -* -* - "h": Express the angle as a time and include an hours field -* (where 24 hours correspond to 360 degrees). Expressing the angle -* purely in hours is also the default if "t" is given without -* either "m" or "s". -* -* - "m": Include a minutes field. By default this is not included. -* -* - "s": Include a seconds field. By default this is not included. -* This request is ignored if "d" or "h" is given, unless a minutes -* field is also included. -* -* - "t": Express the angle as a time (where 24 hours correspond to -* 360 degrees). This option is ignored if either "d" or "h" is -* given and is intended for use where the value is to be expressed -* purely in minutes and/or seconds of time (with no hours -* field). If "t" is given without "d", "h", "m" or "s" being -* present, then it is equivalent to "h". -* -* - ".": Indicates that decimal places are to be given for the -* final field in the formatted string (whichever field this -* is). The "." should be followed immediately by an unsigned -* integer which gives the number of decimal places required, or by an -* asterisk. If an asterisk is supplied, a default number of decimal -* places is used which is based on the value of the Digits -* attribute. -* -* All of the above format specifiers are case-insensitive. If -* several characters make conflicting requests (e.g. if both "i" -* and "b" appear), then the character occurring last takes -* precedence, except that "d" and "h" always override "t". -* -* If the format string starts with a percentage sign (%), then the -* whole format string is assumed to conform to the syntax defined by -* the Frame class, and the axis values is formated as a decimal -* radians value. - -* TimeFrame Formats: -* The Format string supplied for a TimeFrame should either use the -* syntax defined by the base Frame class (i.e. a C "printf" format -* string), or the extended "iso" syntax described below (the default -* value is inherited from the Frame class): -* -* - C "printf" syntax: If the Format string is a C "printf" format -* description such as "%1.7G", the TimeFrame axis value will be -* formatted without change as a floating point value using this format. -* The formatted string will thus represent an offset from the zero point -* specified by the TimeFrame's TimeOrigin attribute, measured in -* units given by the TimeFrame's Unit attribute. -* -* - "iso" syntax: This is used to format a TimeFrame axis value as a -* Gregorian date followed by an optional time of day. If the Format -* value commences with the string "iso" then the TimeFrame axis value -* will be converted to an absolute MJD, including the addition of the -* current TimeOrigin value, and then formatted as a Gregorian date -* using the format "yyyy-mm-dd". Optionally, the Format value may -* include an integer precision following the "iso" specification (e.g. -* "iso.2"), in which case the time of day will be appended to the -* formatted date (if no time of day is included, the date field is -* rounded to the nearest day). The integer value in the Format string -* indicates the number of decimal places to use in the seconds field. For -* instance, a Format value of "iso.0" produces a time of day of the form -* "hh:mm:ss", and a Format value of "iso.2" produces a time of day of the -* form "hh:mm:ss.ss". The date and time fields will be separated by a -* space unless 'T' is appended to the end of string, in which case -* the letter T (upper case) will be used as the separator. The value of -* the Digits attribute is ignored when using this "iso" format. - -* Notes: -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -*att-- -*/ -/* This simply provides an interface to the Axis methods for accessing - the Format string. */ -MAKE_CLEAR(Format) -MAKE_GET(Format,const char *,NULL,0,0) -MAKE_SET(Format,const char *) -MAKE_TEST(Format) - -/* -*att++ -* Name: -* Label(axis) - -* Purpose: -* Axis label. - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute specifies a label to be attached to each axis of -* a Frame when it is represented (e.g.) in graphical output. -* -* If a Label value has not been set for a Frame axis, then a -* suitable default is supplied. - -* Applicability: -* Frame -* The default supplied by the Frame class is the string "Axis -* <n>", where <n> is 1, 2, etc. for each successive axis. -* SkyFrame -* The SkyFrame class re-defines the default Label value -* (e.g. to "Right ascension" or "Galactic latitude") as -* appropriate for the particular celestial coordinate system -* being represented. -* TimeFrame -* The TimeFrame class re-defines the default Label value as -* appropriate for the particular time system being represented. -* FrameSet -* The Label attribute of a FrameSet axis is the same as that of -* its current Frame (as specified by the Current attribute). - -* Notes: -* - Axis labels are intended purely for interpretation by human -* readers and not by software. -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -*att-- -*/ -/* This provides an interface to the Axis methods for accessing the - Label string, but provides an alternative default Label based on - the axis number. This default string is written to the static - "label_buff" buffer and a pointer to this is returned if - required. */ -MAKE_CLEAR(Label) -MAKE_GET(Label,const char *,NULL,1,GetDefaultLabel( axis, status )) -MAKE_SET(Label,const char *) -MAKE_TEST(Label) - -/* -*att++ -* Name: -* Symbol(axis) - -* Purpose: -* Axis symbol. - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute specifies a short-form symbol to be used to -* represent coordinate values for a particular axis of a -* Frame. This might be used (e.g.) in algebraic expressions where -* a full description of the axis would be inappropriate. Examples -* include "RA" and "Dec" (for Right Ascension and Declination). -* -* If a Symbol value has not been set for a Frame axis, then a -* suitable default is supplied. - -* Applicability: -* Frame -* The default Symbol value supplied by the Frame class is the -* string "<Domain><n>", where <n> is 1, 2, etc. for successive -* axes, and <Domain> is the value of the Frame's Domain -* attribute (truncated if necessary so that the final string -* does not exceed 15 characters). If no Domain value has been -* set, "x" is used as the <Domain> value in constructing this -* default string. -* SkyFrame -* The SkyFrame class re-defines the default Symbol value -* (e.g. to "RA" or "Dec") as appropriate for the particular -* celestial coordinate system being represented. -* TimeFrame -* The TimeFrame class re-defines the default Symbol value as -* appropriate for the particular time system being represented. -* FrameSet -* The Symbol attribute of a FrameSet axis is the same as that -* of its current Frame (as specified by the Current attribute). - -* Notes: -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -*att-- -*/ -/* This provides an interface to the Axis methods for accessing the - Symbol string, but provides an alternative default Symbol based on - the axis number and the Frame's Domain (if defined, otherwise "x" - is used). This default string is written to the static - "symbol_buff" buffer and a pointer to this is returned if - required. */ -MAKE_CLEAR(Symbol) -MAKE_GET(Symbol,const char *,NULL,1,GetDefaultSymbol( this, axis, status ) ) -MAKE_SET(Symbol,const char *) -MAKE_TEST(Symbol) - -/* -*att++ -* Name: -* Unit(axis) - -* Purpose: -* Physical units for formatted axis values - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute contains a textual representation of the physical -* units used to represent formatted coordinate values on a particular -* axis of a Frame. -c The astSetActiveUnit function controls how the Unit values -f The AST_SETACTIVEUNIT routine controls how the Unit values -* are used. - -* Applicability: -* Frame -* The default supplied by the Frame class is an empty string. -* SkyFrame -* The SkyFrame class re-defines the default Unit value (e.g. to -* "hh:mm:ss.sss") to describe the character string returned by -c the astFormat function when formatting coordinate values. -f the AST_FORMAT function when formatting coordinate values. -* SpecFrame -* The SpecFrame class re-defines the default Unit value so that it -* is appropriate for the current System value. See the System -* attribute for details. An error will be reported if an attempt -* is made to use an inappropriate Unit. -* TimeFrame -* The TimeFrame class re-defines the default Unit value so that it -* is appropriate for the current System value. See the System -* attribute for details. An error will be reported if an attempt -* is made to use an inappropriate Unit (e.g. "km"). -* FrameSet -* The Unit attribute of a FrameSet axis is the same as that of -* its current Frame (as specified by the Current attribute). - -* Notes: -* - This attribute described the units used when an axis value is -* formatted into a string using -c astFormat. -f AST_FORMAT. -* In some cases these units may be different to those used to represent -* floating point axis values within application code (for instance a -* SkyFrame always uses radians to represent floating point axis values). -* The InternalUnit attribute described the units used for floating -* point values. -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -*att-- -*/ -/* This simply provides an interface to the Axis methods for accessing - the Unit string. */ -MAKE_GET(Unit,const char *,NULL,0,0) -MAKE_TEST(Unit) - -/* -*att++ -* Name: -* NormUnit(axis) - -* Purpose: -* Normalised physical units for formatted axis values - -* Type: -* Public attribute. - -* Synopsis: -* String, read-only. - -* Description: -* The value of this read-only attribute is derived from the current -* value of the Unit attribute. It will represent an equivalent system -* of units to the Unit attribute, but will potentially be simplified. -* For instance, if Unit is set to "s*(m/s)", the NormUnit value will -* be "m". If no simplification can be performed, the value of the -* NormUnit attribute will equal that of the Unit attribute. - -* Applicability: -* Frame -* All Frames have this attribute. - -* Notes: -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -*att-- -*/ -/* This simply provides an interface to the Axis methods for accessing - the NormUnit string. */ -MAKE_GET(NormUnit,const char *,NULL,0,0) - -/* -*att++ -* Name: -* InternalUnit(axis) - -* Purpose: -* Physical units for unformated axis values - -* Type: -* Public attribute. - -* Synopsis: -* String, read-only. - -* Description: -* This read-only attribute contains a textual representation of the -* physical units used to represent unformatted (i.e. floating point) -* values on a particular axis of a Frame, typically handled internally -* within application code. In most cases, the value of the InternalUnit -* attribute will be the same as Unit attribute (i.e. formatted and -* unformatted axis values will normally use the same system of units). -* The main exception to this is the SkyFrame class, which represents -* unformatted axis values in radians, regardless of the current -* setting of the Unit attribute. - -* Applicability: -* Frame -* All Frames have this attribute. - -* Notes: -* - When specifying this attribute by name, it should be -* subscripted with the number of the Frame axis to which it -* applies. -*att-- -*/ -/* If the Axis structure provides a value for InternalUnit, then use - that value. Otherwise, use a default equal to the value of the Unit - attribute for the axis. */ -MAKE_GET(InternalUnit,const char *,NULL,1,astGetUnit(this,axis)) - -/* Implement member functions to access the attributes associated with - the Frame as a whole using the macros defined for this purpose in - the "object.h" file. */ - -/* -*att++ -* Name: -* Digits/Digits(axis) - -* Purpose: -* Number of digits of precision. - -* Type: -* Public attribute. - -* Synopsis: -* Integer. - -* Description: -* This attribute specifies how many digits of precision are -* required by default when a coordinate value is formatted for a -c Frame axis (e.g. using astFormat). Its value may be set either -f Frame axis (e.g. using AST_FORMAT). Its value may be set either -* for a Frame as a whole, or (by subscripting the attribute name -* with the number of an axis) for each axis individually. Any -* value set for an individual axis will over-ride the value for -* the Frame as a whole. -* -* Note that the Digits value acts only as a means of determining a -* default Format string. Its effects are over-ridden if a Format -* string is set explicitly for an axis. However, if the Format -* attribute specifies the precision using the string ".*", then -* the Digits attribute is used to determine the number of decimal -* places to produce. - -* Applicability: -* Frame -* The default Digits value supplied by the Frame class is 7. If -* a value less than 1 is supplied, then 1 is used instead. -* FrameSet -* The Digits attribute of a FrameSet (or one of its axes) is -* the same as that of its current Frame (as specified by the -* Current attribute). -* Plot -* The default Digits value used by the Plot class when drawing -* annotated axis labels is the smallest value which results in all -* adjacent labels being distinct. -* TimeFrame -* The Digits attribute is ignored when a TimeFrame formats a value -* as a date and time string (see the Format attribute). -*att-- -*/ -/* Clear the Digits value by setting it to -INT_MAX. */ -astMAKE_CLEAR(Frame,Digits,digits,-INT_MAX) - -/* Supply a default of 7 digits if no value has been set. */ -astMAKE_GET(Frame,Digits,int,0,( ( this->digits != -INT_MAX ) ? this->digits : - 7 )) - -/* Constrain the Digits value being set to be at least 1. */ -astMAKE_SET(Frame,Digits,int,digits,( value > 1 ? value : 1 )) - -/* The Digits value is set if it is not -INT_MAX. */ -astMAKE_TEST(Frame,Digits,( this->digits != -INT_MAX )) - -/* -*att++ -* Name: -* MatchEnd - -* Purpose: -* Match trailing axes? - -* Type: -* Public attribute. - -* Synopsis: -* Integer (boolean). - -* Description: -* This attribute is a boolean value which controls how a Frame -c behaves when it is used (by astFindFrame) as a template to match -f behaves when it is used (by AST_FINDFRAME) as a template to match -* another (target) Frame. It applies only in the case where a -* match occurs between template and target Frames with different -* numbers of axes. -* -* If the MatchEnd value of the template Frame is zero, then the -* axes which occur first in the target Frame will be matched and -* any trailing axes (in either the target or template) will be -* disregarded. If it is non-zero, the final axes in each Frame -* will be matched and any un-matched leading axes will be -* disregarded instead. - -* Applicability: -* Frame -* The default MatchEnd value for a Frame is zero, so that -* trailing axes are disregarded. -* FrameSet -* The MatchEnd attribute of a FrameSet is the same as that of -* its current Frame (as specified by the Current attribute). -*att-- -*/ -/* Clear the MatchEnd value by setting it to -INT_MAX. */ -astMAKE_CLEAR(Frame,MatchEnd,match_end,-INT_MAX) - -/* Supply a default of 0 if no MatchEnd value has been set. */ -astMAKE_GET(Frame,MatchEnd,int,0,( ( this->match_end != -INT_MAX ) ? - this->match_end : 0 )) - -/* Set a MatchEnd value of 1 if any non-zero value is supplied. */ -astMAKE_SET(Frame,MatchEnd,int,match_end,( value != 0 )) - -/* The MatchEnd value is set if it is not -INT_MAX. */ -astMAKE_TEST(Frame,MatchEnd,( this->match_end != -INT_MAX )) - -/* -*att++ -* Name: -* MaxAxes - -* Purpose: -* Maximum number of Frame axes to match. - -* Type: -* Public attribute. - -* Synopsis: -* Integer. - -* Description: -* This attribute controls how a Frame behaves when it is used (by -c astFindFrame) as a template to match another (target) Frame. It -f AST_FINDFRAME) as a template to match another (target) Frame. It -* specifies the maximum number of axes that the target Frame may -* have in order to match the template. -* -* Normally, this value will equal the number of Frame axes, so -* that a template Frame will only match another Frame with the -* same number of axes as itself. By setting a different value, -* however, the matching process may be used to identify Frames -* with specified numbers of axes. - -* Applicability: -* Frame -* The default MaxAxes value for a Frame is equal to the number -* of Frame axes (Naxes attribute). -* CmpFrame -* The MaxAxes attribute of a CmpFrame defaults to a large number -* (1000000) which is much larger than any likely number of axes in -* a Frame. Combined with the MinAxes default of zero (for a -* CmpFrame), this means that the default behaviour for a CmpFrame -* is to match any target Frame that consists of a subset of the -* axes in the template CmpFrame. To change this so that a CmpFrame -* will only match Frames that have the same number of axes, you -* should set the CmpFrame MaxAxes and MinAxes attributes to the -* number of axes in the CmpFrame. -* FrameSet -* The MaxAxes attribute of a FrameSet is the same as that of -* its current Frame (as specified by the Current attribute). - -* Notes: -* - When setting a MaxAxes value, the value of the MinAxes -* attribute may also be silently changed so that it remains -* consistent with (i.e. does not exceed) the new value. The -* default MaxAxes value may also be reduced to remain consistent -* with the MinAxes value. -* - If a template Frame is used to match a target with a different -* number of axes, the MatchEnd attribute of the template is used -* to determine how the individual axes of each Frame should match. -*att-- -*/ -/* Clear the MaxAxes value by setting it to -INT_MAX. */ -astMAKE_CLEAR(Frame,MaxAxes,max_axes,-INT_MAX) - -/* Use the DefaultMaxAxes and ConsistentMaxAxes functions (defined earlier) for - the Get and Set operations to ensure that MinAxes and MaxAxes values remain - consistent. */ -astMAKE_GET(Frame,MaxAxes,int,0,DefaultMaxAxes( this, status )) -astMAKE_SET(Frame,MaxAxes,int,max_axes,ConsistentMaxAxes( this, value, status )) - -/* The MaxAxes value is set if it is not -INT_MAX. */ -astMAKE_TEST(Frame,MaxAxes,( this->max_axes != -INT_MAX )) - -/* -*att++ -* Name: -* MinAxes - -* Purpose: -* Minimum number of Frame axes to match. - -* Type: -* Public attribute. - -* Synopsis: -* Integer. - -* Description: -* This attribute controls how a Frame behaves when it is used (by -c astFindFrame) as a template to match another (target) Frame. It -f AST_FINDFRAME) as a template to match another (target) Frame. It -* specifies the minimum number of axes that the target Frame may -* have in order to match the template. -* -* Normally, this value will equal the number of Frame axes, so -* that a template Frame will only match another Frame with the -* same number of axes as itself. By setting a different value, -* however, the matching process may be used to identify Frames -* with specified numbers of axes. - -* Applicability: -* Frame -* The default MinAxes value for a Frame is equal to the number -* of Frame axes (Naxes attribute). -* CmpFrame -* The MinAxes attribute of a CmpFrame defaults to zero. Combined -* with the MaxAxes default of 1000000 (for a CmpFrame), this means -* that the default behaviour for a CmpFrame is to match any target -* Frame that consists of a subset of the axes in the template -* CmpFrame. To change this so that a CmpFrame will only match Frames -* that have the same number of axes, you should set the CmpFrame -* MinAxes and MaxAxes attributes to the number of axes in the CmpFrame. -* FrameSet -* The MinAxes attribute of a FrameSet is the same as that of -* its current Frame (as specified by the Current attribute). - -* Notes: -* - When setting a MinAxes value, the value of the MaxAxes -* attribute may also be silently changed so that it remains -* consistent with (i.e. is not less than) the new value. The -* default MinAxes value may also be reduced to remain consistent -* with the MaxAxes value. -* - If a template Frame is used to match a target with a different -* number of axes, the MatchEnd attribute of the template is used -* to determine how the individual axes of each Frame should match. -*att-- -*/ -/* Clear the MinAxes value by setting it to -INT_MAX. */ -astMAKE_CLEAR(Frame,MinAxes,min_axes,-INT_MAX) - -/* Use the DefaultMinAxes and ConsistentMinAxes functions (defined earlier) for - the Get and Set operations to ensure that MinAxes and MaxAxes values remain - consistent. */ -astMAKE_GET(Frame,MinAxes,int,0,DefaultMinAxes( this, status )) -astMAKE_SET(Frame,MinAxes,int,min_axes,ConsistentMinAxes( this, value, status )) - -/* The MinAxes value is set if it is not -INT_MAX. */ -astMAKE_TEST(Frame,MinAxes,( this->min_axes != -INT_MAX )) - -/* -*att++ -* Name: -* Domain - -* Purpose: -* Coordinate system domain. - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute contains a string which identifies the physical -* domain of the coordinate system that a Frame describes. -* -* The Domain attribute also controls how a Frame behaves when it is -c used (by astFindFrame) as a template to match another (target) -f used (by AST_FINDFRAME) as a template to match another (target) -* Frame. It does this by specifying the Domain that the target -* Frame should have in order to match the template. If the Domain -* value in the template Frame is set, then only targets with the -* same Domain value will be matched. If the template's Domain -* value is not set, however, then the target's Domain will be -* ignored. - -* Applicability: -* Frame -* The default Domain value supplied by the Frame class is an -* empty string. -* SkyFrame -* The SkyFrame class re-defines the default Domain value to be -* "SKY". -* CmpFrame -* The CmpFrame class re-defines the default Domain value to be -* of the form "<dom1>-<dom2>", where <dom1> and <dom2> are the -* Domains of the two component Frames. If both these Domains are -* blank, then the string "CMP" is used as the default Domain name. -* FrameSet -* The Domain attribute of a FrameSet is the same as that of its -* current Frame (as specified by the Current attribute). -* SpecFrame -* The SpecFrame class re-defines the default Domain value to be -* "SPECTRUM". -* DSBSpecFrame -* The DSBSpecFrame class re-defines the default Domain value to be -* "DSBSPECTRUM". -* FluxFrame -* The FluxFrame class re-defines the default Domain value to be -* "FLUX". -* SpecFluxFrame -* The FluxFrame class re-defines the default Domain value to be -* "SPECTRUM-FLUX". -* TimeFrame -* The TimeFrame class re-defines the default Domain value to be -* "TIME". - -* Notes: -* - All Domain values are converted to upper case and white space -* is removed before use. -*att-- -*/ -/* Clear the Domain value by freeing the allocated memory and - assigning a NULL pointer. */ -astMAKE_CLEAR(Frame,Domain,domain,astFree( this->domain )) - -/* If the Domain value is not set, supply a default in the form of a - pointer to the constant string "". */ -astMAKE_GET(Frame,Domain,const char *,NULL,( this->domain ? this->domain : - "" )) - -/* Set a Domain value by freeing any previously allocated memory, - allocating new memory, storing the string, removing white space, - converting to upper case and saving the pointer to the cleaned - copy. */ -astMAKE_SET(Frame,Domain,const char *,domain,CleanDomain( - astStore( this->domain, - value, strlen( value ) + (size_t) 1 ), status )) - -/* The Domain value is set if the pointer to it is not NULL. */ -astMAKE_TEST(Frame,Domain,( this->domain != NULL )) - -/* -*att++ -* Name: -* Permute - -* Purpose: -* Permute axis order? - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute is a boolean value which controls how a Frame -c behaves when it is used (by astFindFrame) as a template to match -f behaves when it is used (by AST_FINDFRAME) as a template to match -* another (target) Frame. It specifies whether the axis order of -* the target Frame may be permuted in order to obtain a match. -* -* If the template's Permute value is zero, it will match a target -* only if it can do so without changing the order of its -* axes. Otherwise, it will attempt to permute the target's axes as -* necessary. -* -* The default value is 1, so that axis permutation will be attempted. - -* Applicability: -* Frame -* All Frames have this attribute. However, the Frame class -* effectively ignores this attribute and behaves as if it has -* the value 1. This is because the axes of a basic Frame are -* not distinguishable and will always match any other Frame -* whatever their order. -* SkyFrame -* Unlike a basic Frame, the SkyFrame class makes use of this -* attribute. -* FrameSet -* The Permute attribute of a FrameSet is the same as that of -* its current Frame (as specified by the Current attribute). -*att-- -*/ -/* Clear the Permute value by setting it to -INT_MAX. */ -astMAKE_CLEAR(Frame,Permute,permute,-INT_MAX) - -/* Supply a default of 1 if no Permute value has been set. */ -astMAKE_GET(Frame,Permute,int,0,( ( this->permute != -INT_MAX ) ? - this->permute : 1 )) - -/* Set a Permute value of 1 if any non-zero value is supplied. */ -astMAKE_SET(Frame,Permute,int,permute,( value != 0 )) - -/* The Permute value is set if it is not -INT_MAX. */ -astMAKE_TEST(Frame,Permute,( this->permute != -INT_MAX )) - -/* -*att++ -* Name: -* PreserveAxes - -* Purpose: -* Preserve axes? - -* Type: -* Public attribute. - -* Synopsis: -* Integer (boolean). - -* Description: -* This attribute controls how a Frame behaves when it is used (by -c astFindFrame) as a template to match another (target) Frame. It -f AST_FINDFRAME) as a template to match another (target) Frame. It -* determines which axes appear (and in what order) in the "result" -* Frame produced. -* -* If PreserveAxes is zero in the template Frame, then the result -* Frame will have the same number (and order) of axes as the -* template. If it is non-zero, however, the axes of the target -* Frame will be preserved, so that the result Frame will have the -* same number (and order) of axes as the target. -* -* The default value is zero, so that target axes are not preserved -* and the result Frame resembles the template. - -* Applicability: -* Frame -* All Frames have this attribute. -* FrameSet -* The PreserveAxes attribute of a FrameSet is the same as that -* of its current Frame (as specified by the Current attribute). -*att-- -*/ -/* Clear the PreserveAxes value by setting it to -INT_MAX. */ -astMAKE_CLEAR(Frame,PreserveAxes,preserve_axes,-INT_MAX) - -/* Supply a default of 0 if no PreserveAxes value has been set. */ -astMAKE_GET(Frame,PreserveAxes,int,0,( ( this->preserve_axes != -INT_MAX ) ? - this->preserve_axes : 0 )) - -/* Set a PreserveAxes value of 1 if any non-zero value is supplied. */ -astMAKE_SET(Frame,PreserveAxes,int,preserve_axes,( value != 0 )) - -/* The PreserveAxes value is set if it is not -INT_MAX. */ -astMAKE_TEST(Frame,PreserveAxes,( this->preserve_axes != -INT_MAX )) - -/* -*att++ -* Name: -* AlignSystem - -* Purpose: -* Coordinate system in which to align the Frame. - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute controls how a Frame behaves when it is used (by -c astFindFrame or astConvert) as a template to match another (target) -f AST_FINDFRAME or AST_CONVERT) as a template to match another (target) -* Frame. It identifies the coordinate system in which the two Frames -* will be aligned by the match. -* -* The values which may be assigned to this attribute, and its default -* value, depend on the class of Frame and are described in the -* "Applicability" section below. In general, the AlignSystem attribute -* will accept any of the values which may be assigned to the System -* attribute. -* -c The Mapping returned by AST_FINDFRAME or AST_CONVERT will use the -f The Mapping returned by astFindFrame or astConvert will use the -* coordinate system specified by the AlignSystem attribute as an -* intermediate coordinate system. The total returned Mapping will first -* map positions from the first Frame into this intermediate coordinate -* system, using the attributes of the first Frame. It will then map -* these positions from the intermediate coordinate system into the -* second Frame, using the attributes of the second Frame. - -* Applicability: -* Frame -* The AlignSystem attribute for a basic Frame always equals "Cartesian", -* and may not be altered. -* CmpFrame -* The AlignSystem attribute for a CmpFrame always equals "Compound", -* and may not be altered. -* FrameSet -* The AlignSystem attribute of a FrameSet is the same as that of its -* current Frame (as specified by the Current attribute). -* SkyFrame -* The default AlignSystem attribute for a SkyFrame is "ICRS". -* SpecFrame -* The default AlignSystem attribute for a SpecFrame is "Wave" -* (wavelength). -* TimeFrame -* The default AlignSystem attribute for a TimeFrame is "MJD". -*att-- -*/ -/* Clear the AlignSystem value by setting it to AST__BADSYSTEM. */ -astMAKE_CLEAR(Frame,AlignSystem,alignsystem,AST__BADSYSTEM) - -/* Provide a default AlignSystem of AST__CART. */ -astMAKE_GET(Frame,AlignSystem,AstSystemType,AST__BADSYSTEM,( - ( this->alignsystem == AST__BADSYSTEM ) ? AST__CART : this->alignsystem ) ) - -/* Validate the AlignSystem value being set and retain the original if the - supplied value is not recognized. */ -astMAKE_SET(Frame,AlignSystem,AstSystemType,alignsystem,( - (astValidateSystem( this, value, "astSetAlignSystem" ) != AST__BADSYSTEM) ? - value : this->alignsystem )) - -/* The AlignSystem value is set if it is not AST__BADSYSTEM. */ -astMAKE_TEST(Frame,AlignSystem,( this->alignsystem != AST__BADSYSTEM )) - -/* -*att++ -* Name: -* System - -* Purpose: -* Coordinate system used to describe positions within the domain - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* In general it is possible for positions within a given physical -* domain to be described using one of several different coordinate -* systems. For instance, the SkyFrame class can use galactic -* coordinates, equatorial coordinates, etc, to describe positions on -* the sky. As another example, the SpecFrame class can use frequency, -* wavelength, velocity, etc, to describe a position within an -* electromagnetic spectrum. The System attribute identifies the particular -* coordinate system represented by a Frame. Each class of Frame -* defines a set of acceptable values for this attribute, as listed -* below (all are case insensitive). Where more than one alternative -* System value is shown, the first of will be returned when an -* enquiry is made. - -* Applicability: -* Frame -* The System attribute for a basic Frame always equals "Cartesian", -* and may not be altered. -* CmpFrame -* The System attribute for a CmpFrame always equals "Compound", -* and may not be altered. In addition, the CmpFrame class allows -* the System attribute to be referenced for a component Frame by -* including the index of an axis within the required component -* Frame. For instance, "System(3)" refers to the System attribute -* of the component Frame which includes axis 3 of the CmpFrame. -* FrameSet -* The System attribute of a FrameSet is the same as that of its -* current Frame (as specified by the Current attribute). -* SkyFrame -* The SkyFrame class supports the following System values and -* associated celestial coordinate systems: -* -* - "AZEL": Horizon coordinates. The longitude axis is azimuth -* such that geographic north has an azimuth of zero and geographic -* east has an azimuth of +PI/2 radians. The zenith has elevation -* +PI/2. When converting to and from other celestial coordinate -* systems, no corrections are applied for atmospheric refraction -* or polar motion (however, a correction for diurnal aberattion is -* applied). Note, unlike most other -* celestial coordinate systems, this system is right handed. Also, -* unlike other SkyFrame systems, the AzEl system is sensitive to -* the timescale in which the Epoch value is supplied. This is -* because of the gross diurnal rotation which this system undergoes, -* causing a small change in time to translate to a large rotation. -* When converting to or from an AzEl system, the Epoch value for -* both source and destination SkyFrames should be supplied in the -* TDB timescale. The difference between TDB and TT is between 1 -* and 2 milliseconds, and so a TT value can usually be supplied in -* place of a TDB value. The TT timescale is related to TAI via -* TT = TAI + 32.184 seconds. -* -* - "ECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the -* ecliptic and mean equinox specified by the qualifying Equinox -* value. -* -* - "FK4": The old FK4 (barycentric) equatorial coordinate system, -* which should be qualified by an Equinox value. The underlying -* model on which this is based is non-inertial and rotates slowly -* with time, so for accurate work FK4 coordinate systems should -* also be qualified by an Epoch value. -* -* - "FK4-NO-E" or "FK4_NO_E": The old FK4 (barycentric) equatorial -* system but without the "E-terms of aberration" (e.g. some radio -* catalogues). This coordinate system should also be qualified by -* both an Equinox and an Epoch value. -* -* - "FK5" or "EQUATORIAL": The modern FK5 (barycentric) equatorial -* coordinate system. This should be qualified by an Equinox value. -* -* - "GALACTIC": Galactic coordinates (IAU 1958). -* -* - "GAPPT", "GEOCENTRIC" or "APPARENT": The geocentric apparent -* equatorial coordinate system, which gives the apparent positions -* of sources relative to the true plane of the Earth's equator and -* the equinox (the coordinate origin) at a time specified by the -* qualifying Epoch value. (Note that no Equinox is needed to -* qualify this coordinate system because no model "mean equinox" -* is involved.) These coordinates give the apparent right -* ascension and declination of a source for a specified date of -* observation, and therefore form an approximate basis for -* pointing a telescope. Note, however, that they are applicable to -* a fictitious observer at the Earth's centre, and therefore -* ignore such effects as atmospheric refraction and the (normally -* much smaller) aberration of light due to the rotational velocity -* of the Earth's surface. Geocentric apparent coordinates are -* derived from the standard FK5 (J2000.0) barycentric coordinates -* by taking account of the gravitational deflection of light by -* the Sun (usually small), the aberration of light caused by the -* motion of the Earth's centre with respect to the barycentre -* (larger), and the precession and nutation of the Earth's spin -* axis (normally larger still). -* -* - "HELIOECLIPTIC": Ecliptic coordinates (IAU 1980), referred to the -* ecliptic and mean equinox of J2000.0, in which an offset is added to -* the longitude value which results in the centre of the sun being at -* zero longitude at the date given by the Epoch attribute. Attempts to -* set a value for the Equinox attribute will be ignored, since this -* system is always referred to J2000.0. -* -* - "ICRS": The Internation Celestial Reference System, realised -* through the Hipparcos catalogue. Whilst not an equatorial system -* by definition, the ICRS is very close to the FK5 (J2000) system -* and is usually treated as an equatorial system. The distinction -* between ICRS and FK5 (J2000) only becomes important when accuracies -* of 50 milli-arcseconds or better are required. ICRS need not be -* qualified by an Equinox value. -* -* - "J2000": An equatorial coordinate system based on the mean -* dynamical equator and equinox of the J2000 epoch. The dynamical -* equator and equinox differ slightly from those used by the FK5 -* model, and so a "J2000" SkyFrame will differ slightly from an -* "FK5(Equinox=J2000)" SkyFrame. The J2000 System need not be -* qualified by an Equinox value -* -* - "SUPERGALACTIC": De Vaucouleurs Supergalactic coordinates. -* -* - "UNKNOWN": Any other general spherical coordinate system. No -* Mapping can be created between a pair of SkyFrames if either of the -* SkyFrames has System set to "Unknown". -* -* Currently, the default System value is "ICRS". However, this -* default may change in future as new astrometric standards -* evolve. The intention is to track the most modern appropriate -* standard. For this reason, you should use the default only if -* this is what you intend (and can tolerate any associated slight -* change in future). If you intend to use the ICRS system -* indefinitely, then you should specify it explicitly. -* SpecFrame -* The SpecFrame class supports the following System values and -* associated spectral coordinate systems (the default is "WAVE" - -* wavelength). They are all defined in FITS-WCS paper III: -* -* - "FREQ": Frequency (GHz) -* - "ENER" or "ENERGY": Energy (J) -* - "WAVN" or "WAVENUM": Wave-number (1/m) -* - "WAVE" or "WAVELEN": Vacuum wave-length (Angstrom) -* - "AWAV" or "AIRWAVE": Wave-length in air (Angstrom) -* - "VRAD" or "VRADIO": Radio velocity (km/s) -* - "VOPT" or "VOPTICAL": Optical velocity (km/s) -* - "ZOPT" or "REDSHIFT": Redshift (dimensionless) -* - "BETA": Beta factor (dimensionless) -* - "VELO" or "VREL": Apparent radial ("relativistic") velocity (km/s) -* -* The default value for the Unit attribute for each system is shown -* in parentheses. Note that the default value for the ActiveUnit flag -c is non-zero -f is .TRUE. -* for a SpecFrame, meaning that changes to the Unit attribute for -* a SpecFrame will result in the SpecFrame being re-mapped within -* its enclosing FrameSet in order to reflect the change in units -c (see astSetActiveUnit function for further information). -f (see AST_SETACTIVEUNIT routine for further information). -* TimeFrame -* The TimeFrame class supports the following System values and -* associated coordinate systems (the default is "MJD"): -* -* - "MJD": Modified Julian Date (d) -* - "JD": Julian Date (d) -* - "JEPOCH": Julian epoch (yr) -* - "BEPOCH": Besselian (yr) -* -* The default value for the Unit attribute for each system is shown -* in parentheses. Strictly, these systems should not allow changes -* to be made to the units. For instance, the usual definition of -* "MJD" and "JD" include the statement that the values will be in -* units of days. However, AST does allow the use of other units -* with all the above supported systems (except BEPOCH), on the -* understanding that conversion to the "correct" units involves -* nothing more than a simple scaling (1 yr = 365.25 d, 1 d = 24 h, -* 1 h = 60 min, 1 min = 60 s). Besselian epoch values are defined -* in terms of tropical years of 365.2422 days, rather than the -* usual Julian year of 365.25 days. Therefore, to avoid any -* confusion, the Unit attribute is automatically cleared to "yr" when -* a System value of BEPOCH System is selected, and an error is -* reported if any attempt is subsequently made to change the Unit -* attribute. -* -* Note that the default value for the ActiveUnit flag -c is non-zero -f is .TRUE. -* for a TimeFrame, meaning that changes to the Unit attribute for -* a TimeFrame will result in the TimeFrame being re-mapped within -* its enclosing FrameSet in order to reflect the change in units -c (see astSetActiveUnit function for further information). -f (see AST_SETACTIVEUNIT routine for further information). -* FluxFrame -* The FluxFrame class supports the following System values and -* associated systems for measuring observed value: -* -* - "FLXDN": Flux per unit frequency (W/m^2/Hz) -* - "FLXDNW": Flux per unit wavelength (W/m^2/Angstrom) -* - "SFCBR": Surface brightness in frequency units (W/m^2/Hz/arcmin**2) -* - "SFCBRW": Surface brightness in wavelength units (W/m^2/Angstrom/arcmin**2) -* -* The above lists specified the default units for each System. If an -* explicit value is set for the Unit attribute but no value is set -* for System, then the default System value is determined by the Unit -* string (if the units are not appropriate for describing any of the -* supported Systems then an error will be reported when an attempt is -* made to access the System value). If no value has been specified for -* either Unit or System, then System=FLXDN and Unit=W/m^2/Hz are -* used. -*att-- -*/ -/* Clear the System value by setting it to AST__BADSYSTEM. */ -astMAKE_CLEAR(Frame,System,system,AST__BADSYSTEM) - -/* Provide a default coordinate system of AST__CART. */ -astMAKE_GET(Frame,System,AstSystemType,AST__BADSYSTEM,( - ( this->system == AST__BADSYSTEM ) ? AST__CART : this->system ) ) - -/* Validate the System value being set and retain the original if the - supplied value is not recognized. */ -astMAKE_SET(Frame,System,AstSystemType,system,( - (astValidateSystem( this, value, "astSetSystem" ) != AST__BADSYSTEM) ? - value : this->system )) - -/* The System value is set if it is not AST__BADSYSTEM. */ -astMAKE_TEST(Frame,System,( this->system != AST__BADSYSTEM )) - -/* -*att++ -* Name: -* Title - -* Purpose: -* Frame title. - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute holds a string which is used as a title in (e.g.) -* graphical output to describe the coordinate system which a Frame -* represents. Examples might be "Detector Coordinates" or -* "Galactic Coordinates". -* -* If a Title value has not been set for a Frame, then a suitable -* default is supplied, depending on the class of the Frame. - -* Applicability: -* Frame -* The default supplied by the Frame class is "<n>-d coordinate -* system", where <n> is the number of Frame axes (Naxes -* attribute). -* CmpFrame -* The CmpFrame class re-defines the default Title value to be -* "<n>-d compound coordinate system", where <n> is the number -* of CmpFrame axes (Naxes attribute). -* FrameSet -* The Title attribute of a FrameSet is the same as that of its -* current Frame (as specified by the Current attribute). - -* Notes: -* - A Frame's Title is intended purely for interpretation by human -* readers and not by software. -*att-- -*/ -/* Clear the Title value by freeing the allocated memory and assigning - a NULL pointer. */ -astMAKE_CLEAR(Frame,Title,title,astFree( this->title )) - -/* If the Title value is not set, write a default based on the number of Frame - axes into the static "title_buff" buffer, and return a pointer to this - buffer. */ -astMAKE_GET(Frame,Title,const char *,NULL,( this->title ? - this->title : GetDefaultTitle( this, status ) )) - -/* Set a Title value by freeing any previously allocated memory, allocating - new memory, storing the string and saving the pointer to the copy. */ -astMAKE_SET(Frame,Title,const char *,title,astStore( this->title, value, - strlen( value ) + (size_t) 1 )) - -/* The Title value is set if the pointer to it is not NULL. */ -astMAKE_TEST(Frame,Title,( this->title != NULL )) - -/* -*att++ -* Name: -* ObsLat - -* Purpose: -* The geodetic latitude of the observer - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute specifies the geodetic latitude of the observer, in -* degrees, relative to the IAU 1976 reference ellipsoid. The basic Frame -* class makes no use of this attribute, but specialised subclasses of -* Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame -* classes use it. The default value is zero. -* -* The value is stored internally in radians, but is converted to and -* from a degrees string for access. Some example input formats are: -* "22:19:23.2", "22 19 23.2", "22:19.387", "22.32311", "N22.32311", -* "-45.6", "S45.6". As indicated, the sign of the latitude can -* optionally be indicated using characters "N" and "S" in place of the -* usual "+" and "-". When converting the stored value to a string, the -* format "[s]dd:mm:ss.ss" is used, when "[s]" is "N" or "S". - -* Applicability: -* Frame -* All Frames have this attribute. -* SpecFrame -* Together with the ObsLon, Epoch, RefRA and RefDec attributes, -* it defines the Doppler shift introduced by the observers diurnal -* motion around the earths axis, which is needed when converting to -* or from the topocentric standard of rest. The maximum velocity -* error which can be caused by an incorrect value is 0.5 km/s. The -* default value for the attribute is zero. -* TimeFrame -* Together with the ObsLon attribute, it is used when converting -* between certain time scales (TDB, TCB, LMST, LAST) - -*att-- -*/ -/* The geodetic latitude of the observer (radians). Clear the ObsLat value by - setting it to AST__BAD, returning zero as the default value. Any value is - acceptable. */ -astMAKE_CLEAR(Frame,ObsLat,obslat,AST__BAD) -astMAKE_GET(Frame,ObsLat,double,0.0,((this->obslat!=AST__BAD)?this->obslat:0.0)) -astMAKE_SET(Frame,ObsLat,double,obslat,value) -astMAKE_TEST(Frame,ObsLat,(this->obslat!=AST__BAD)) - - -/* -*att++ -* Name: -* ObsAlt - -* Purpose: -* The geodetic altitude of the observer - -* Type: -* Public attribute. - -* Synopsis: -* Floating point. - -* Description: -* This attribute specifies the geodetic altitude of the observer, in -* metres, relative to the IAU 1976 reference ellipsoid. The basic Frame -* class makes no use of this attribute, but specialised subclasses of -* Frame may use it. For instance, the SpecFrame, SkyFrame and TimeFrame -* classes use it. The default value is zero. - -* Applicability: -* Frame -* All Frames have this attribute. -* SpecFrame -* Together with the ObsLon, Epoch, RefRA and RefDec attributes, -* it defines the Doppler shift introduced by the observers diurnal -* motion around the earths axis, which is needed when converting to -* or from the topocentric standard of rest. The maximum velocity -* error which can be caused by an incorrect value is 0.5 km/s. The -* default value for the attribute is zero. -* TimeFrame -* Together with the ObsLon attribute, it is used when converting -* between certain time scales (TDB, TCB, LMST, LAST) - -*att-- -*/ -/* The geodetic altitude of the observer (metres). Clear the ObsAlt value by - setting it to AST__BAD, returning zero as the default value. Any value is - acceptable. */ -astMAKE_CLEAR(Frame,ObsAlt,obsalt,AST__BAD) -astMAKE_GET(Frame,ObsAlt,double,0.0,((this->obsalt!=AST__BAD)?this->obsalt:0.0)) -astMAKE_SET(Frame,ObsAlt,double,obsalt,value) -astMAKE_TEST(Frame,ObsAlt,(this->obsalt!=AST__BAD)) - - -/* -*att++ -* Name: -* ObsLon - -* Purpose: -* The geodetic longitude of the observer - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute specifies the geodetic (or equivalently, geocentric) -* longitude of the observer, in degrees, measured positive eastwards. -* See also attribute ObsLat. The basic Frame class makes no use of this -* attribute, but specialised subclasses of Frame may use it. For instance, -* the SpecFrame, SkyFrame and TimeFrame classes use it. The default value -* is zero. -* -* The value is stored internally in radians, but is converted to and -* from a degrees string for access. Some example input formats are: -* "155:19:23.2", "155 19 23.2", "155:19.387", "155.32311", "E155.32311", -* "-204.67689", "W204.67689". As indicated, the sign of the longitude can -* optionally be indicated using characters "E" and "W" in place of the -* usual "+" and "-". When converting the stored value to a string, the -* format "[s]ddd:mm:ss.ss" is used, when "[s]" is "E" or "W" and the -* numerical value is chosen to be less than 180 degrees. - -* Applicability: -* Frame -* All Frames have this attribute. -* SpecFrame -* Together with the ObsLon, Epoch, RefRA and RefDec attributes, -* it defines the Doppler shift introduced by the observers diurnal -* motion around the earths axis, which is needed when converting to -* or from the topocentric standard of rest. The maximum velocity -* error which can be caused by an incorrect value is 0.5 km/s. The -* default value for the attribute is zero. -* TimeFrame -* Together with the ObsLon attribute, it is used when converting -* between certain time scales (TDB, TCB, LMST, LAST) - -*att-- -*/ -/* The geodetic longitude of the observer (radians). Clear the ObsLon value by - setting it to AST__BAD, returning zero as the default value. Any value is - acceptable. */ -astMAKE_CLEAR(Frame,ObsLon,obslon,AST__BAD) -astMAKE_GET(Frame,ObsLon,double,0.0,((this->obslon!=AST__BAD)?this->obslon:0.0)) -astMAKE_SET(Frame,ObsLon,double,obslon,value) -astMAKE_TEST(Frame,ObsLon,(this->obslon!=AST__BAD)) - - -/* Copy constructor. */ -/* ----------------- */ -static void Copy( const AstObject *objin, AstObject *objout, int *status ) { -/* -* Name: -* Copy - -* Purpose: -* Copy constructor for Frame objects. - -* Type: -* Private function. - -* Synopsis: -* void Copy( const AstObject *objin, AstObject *objout, int *status ) - -* Description: -* This function implements the copy constructor for Frame 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: */ - AstFrame *in; /* Pointer to input Frame */ - AstFrame *out; /* Pointer to output Frame */ - int axis; /* Loop counter for axes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain pointers to the input and output Frames. */ - in = (AstFrame *) objin; - out = (AstFrame *) objout; - -/* For safety, first clear any references to the input memory from - the output Frame. */ - out->axis = NULL; - out->domain = NULL; - out->perm = NULL; - out->title = NULL; - out->variants = NULL; - -/* If necessary, allocate memory in the output Frame and store a copy of the - input Title and Domain strings. */ - if ( in->title ) out->title = astStore( NULL, in->title, - strlen( in->title ) + (size_t) 1 ); - if ( in->domain ) out->domain = astStore( NULL, in->domain, - strlen( in->domain ) + - (size_t) 1 ); - -/* Allocate memory to hold the output Frame's Axis object pointers and its axis - permutation array. */ - out->axis = astMalloc( sizeof( AstAxis * ) * (size_t) in->naxes ); - out->perm = astMalloc( sizeof( int ) * (size_t) in->naxes ); - -/* Make a copy of each of the input Frame's Axis objects, storing the pointer - to each new Axis in the memory just allocated. Also copy the axis - permutation array. */ - if ( astOK ) { - for ( axis = 0; axis < in->naxes; axis++ ) { - out->axis[ axis ] = astCopy( in->axis[ axis ] ); - out->perm[ axis ] = in->perm[ axis ]; - } - -/* If an error occurred while copying the Axis objects, then loop through the - resulting array of pointers and make sure that all of them are properly - annulled. */ - if ( !astOK ) { - for ( axis = 0; axis < in->naxes; axis++ ) { - out->axis[ axis ] = astAnnul( out->axis[ axis ] ); - } - } - } - -/* Other remaining objects */ - if( in->variants ) out->variants = astCopy( in->variants ); - -/* If an error occurred, free any allocated memory. */ - if ( !astOK ) { - out->axis = astFree( out->axis ); - out->domain = astFree( out->domain ); - out->perm = astFree( out->perm ); - out->title = astFree( out->title ); - } -} - -/* Destructor. */ -/* ----------- */ -static void Delete( AstObject *obj, int *status ) { -/* -* Name: -* Delete - -* Purpose: -* Destructor for Frame objects. - -* Type: -* Private function. - -* Synopsis: -* void Delete( AstObject *obj, int *status ) - -* Description: -* This function implements the destructor for Frame 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: */ - AstFrame *this; /* Pointer to Frame */ - int axis; /* Loop counter for Frame axes */ - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) obj; - -/* Free the memory used for the Title and Domain strings if necessary. */ - this->title = astFree( this->title ); - this->domain = astFree( this->domain ); - -/* If memory has been allocated to store pointers to the Frame's Axis objects, - annul each of these pointers and then free the memory. */ - if ( this->axis ) { - for ( axis = 0; axis < this->naxes; axis++ ) { - this->axis[ axis ] = astAnnul( this->axis[ axis ] ); - } - this->axis = astFree( this->axis ); - } - -/* Free memory used for the axis permutation array if necessary. */ - this->perm = astFree( this->perm ); - -/* Other objects. */ - if( this->variants ) this->variants = astAnnul( this->variants ); -} - -/* Dump function. */ -/* -------------- */ -static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { -/* -* Name: -* Dump - -* Purpose: -* Dump function for Frame 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 Frame class to an output Channel. - -* Parameters: -* this -* Pointer to the Frame 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 COMMENT_LEN 150 /* Maximum length of a comment string */ -#define KEY_LEN 50 /* Maximum length of a keyword */ - -/* Local Variables: */ - AstAxis *ax; /* Pointer to Axis */ - AstFrame *cfrm; /* Pointer to FrameSet's current Frame */ - AstFrame *this; /* Pointer to the Frame structure */ - AstSystemType system; /* System code */ - char comment[ COMMENT_LEN + 1 ]; /* Buffer for comment strings */ - char key[ KEY_LEN + 1 ]; /* Buffer for keywords */ - const char *sval; /* Pointer to string value */ - const char *lab; /* Pointer to unit label */ - const int *perm; /* Pointer to axis permutation array */ - double dval; /* Double attibute value */ - int *invperm; /* Pointer to inverse permutation array */ - int axis; /* Loop counter for Frame axes */ - int bessyr; /* Format as Besselian years (else Julian) */ - int digits_set; /* Digits set explicitly for any axis? */ - int full; /* Full attribute value */ - int full_set; /* Full attribute set? */ - int helpful; /* Helpful to show value even if not set? */ - int isFrame; /* Is this a simple Frame? */ - int ival; /* Integer value */ - int naxes; /* Number of Frame axes */ - int set; /* Attribute value set? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the Frame structure. */ - this = (AstFrame *) this_object; - -/* Determine the number of Frame axes and a pointer to the Frame's - axis permutation array (using methods, to allow for any over-ride - by a derived class). */ - naxes = astGetNaxes( this ); - perm = astGetPerm( this ); - -/* Some default attribute values are not helpful for a simple Frame. Note - if this is a simple Frame, or if it is a FrameSet with a simple Frame - as its current Frame., or if it is a CmpFrame. */ - if( !strcmp( astGetClass( this ), "Frame" ) ) { - isFrame = 1; - } else if( astIsAFrameSet( this ) ) { - cfrm = astGetFrame( (AstFrameSet *) this, AST__CURRENT ); - isFrame = !strcmp( astGetClass( cfrm ), "Frame" ); - cfrm = astAnnul( cfrm ); - } else if( astIsACmpFrame( this ) ) { - isFrame = 1; - } else { - isFrame = 0; - } - -/* Allocate memory to hold an inverse axis permutation array and - generate this array from the forward permutation values. This will - be used to determine which axis should be enquired about (using - possibly over-ridden methods) to obtain data to correspond with a - particular internal value (i.e. instance variable) relating to an - axis. This step is needed so that the effect of any axis - permutation can be un-done before values are written out, as output - values are written by this function in un-permuted order. */ - invperm = astMalloc( sizeof( int ) * (size_t) naxes ); - if ( astOK ) { - for ( axis = 0; axis < naxes; axis++ ) invperm[ perm[ axis ] ] = axis; - -/* Write out values representing the instance variables for the Frame - 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. */ - -/* Title. */ -/* ------ */ - set = TestTitle( this, status ); - sval = set ? GetTitle( this, status ) : astGetTitle( this ); - astWriteString( channel, "Title", set, 1, sval, - "Title of coordinate system" ); - -/* Naxes. */ -/* ------ */ - set = ( this->naxes != 0 ); - ival = set ? this->naxes : naxes; - astWriteInt( channel, "Naxes", set, 1, ival, - "Number of coordinate axes" ); - -/* Domain. */ -/* ------- */ - set = TestDomain( this, status ); - sval = set ? GetDomain( this, status ) : astGetDomain( this ); - -/* Don't show an un-set Domain value if it is blank. */ - helpful = ( sval && *sval ); - astWriteString( channel, "Domain", set, helpful, sval, - "Coordinate system domain" ); - -/* Epoch. */ -/* ------ */ - set = TestEpoch( this, status ); - dval = set ? GetEpoch( this, status ) : astGetEpoch( this ); - -/* Convert MJD to Besselian or Julian years, depending on the value. */ - bessyr = ( dval < palEpj2d( 1984.0 ) ); - dval = bessyr ? palEpb( dval ) : palEpj( dval ); - astWriteDouble( channel, "Epoch", set, !isFrame, dval, - bessyr ? "Besselian epoch of observation" : - "Julian epoch of observation" ); - -/* Label. */ -/* ------ */ -/* This, and some other, attributes are stored internally by the - Frame's Axis objects, but are "re-packaged" by the Frame class to - appear as Frame attributes. We treat them here like Frame - attributes that are "un-set". There is a Label value for each Frame - axis. */ - for ( axis = 0; axis < naxes; axis++ ) { - -/* The inverse axis permutation array is used to obtain the axis index - for astGetLabel. This reverses the effect of the Frame's axis - permutation array and yields a default value appropriate to the - axis with internal index "axis". */ - sval = astGetLabel( this, invperm[ axis ] ); - -/* Create keyword and comment strings appropriate to each axis - (converting to 1-based axis numbering) and write out the Label - values. */ - (void) sprintf( key, "Lbl%d", axis + 1 ); - (void) sprintf( comment, "Label for axis %d", axis + 1 ); - astWriteString( channel, key, 0, 1, sval, comment ); - } - -/* Symbol. */ -/* ------- */ -/* There is a Symbol value for each Frame axis. These are handled in - the same way as the Label values. */ - for ( axis = 0; axis < naxes; axis++ ) { - sval = astGetSymbol( this, invperm[ axis ] ); - (void) sprintf( key, "Sym%d", axis + 1 ); - (void) sprintf( comment, "Symbol for axis %d", axis + 1 ); - astWriteString( channel, key, 0, 0, sval, comment ); - } - -/* System. */ -/* ------- */ - set = TestSystem( this, status ); - system = set ? GetSystem( this, status ) : astGetSystem( this ); - -/* If set, convert explicitly to a string for the external representation. */ - if ( set ) { - if ( astOK ) { - sval = astSystemString( this, system ); - -/* Report an error if the System value was not recognised. */ - if ( !sval ) { - astError( AST__SCSIN, - "astWrite(%s): Corrupt %s contains invalid " - "System identification code (%d).", status, - astGetClass( channel ), astGetClass( this ), - (int) system ); - } - } - -/* If not set, use astGetAttrib which returns a string value using - (possibly over-ridden) methods. */ - } else { - sval = astGetAttrib( this_object, "system" ); - } - -/* Write out the value. */ - astWriteString( channel, "System", set, !isFrame, sval, - "Coordinate system type" ); - -/* AlignSystem. */ -/* ------------ */ - set = TestAlignSystem( this, status ); - system = set ? GetAlignSystem( this, status ) : astGetAlignSystem( this ); - -/* If set, convert explicitly to a string for the external representation. */ - if ( set ) { - if ( astOK ) { - sval = astSystemString( this, system ); - -/* Report an error if the AlignSystem value was not recognised. */ - if ( !sval ) { - astError( AST__SCSIN, - "astWrite(%s): Corrupt %s contains invalid " - "AlignSystem identification code (%d).", status, - astGetClass( channel ), astGetClass( this ), - (int) system ); - } - } - -/* If not set, use astGetAttrib which returns a string value using - (possibly over-ridden) methods. */ - } else { - sval = astGetAttrib( this_object, "alignsystem" ); - } - -/* Write out the value. */ - astWriteString( channel, "AlSys", set, 0, sval, - "Alignment coordinate system" ); - -/* Unit. */ -/* ----- */ -/* There is a Unit value for each axis. */ - for ( axis = 0; axis < naxes; axis++ ) { - sval = astGetUnit( this, invperm[ axis ] ); - -/* Get any label associated with the unit string. */ - lab = astUnitLabel( sval ); - -/* Construct a comment including the above label (but only if it is not - the same as the unit string) . */ - if( lab && strcmp( lab, sval ) ) { - (void) sprintf( comment, "Units for axis %d (%s)", axis + 1, lab ); - } else { - (void) sprintf( comment, "Units for axis %d", axis + 1 ); - } - -/* Show the Unit value if it is not blank. */ - helpful = ( sval && *sval ); - (void) sprintf( key, "Uni%d", axis + 1 ); - astWriteString( channel, key, 0, helpful, sval, comment ); - } - -/* Digits. */ -/* ------- */ -/* There is a Digits value for each axis... */ - digits_set = 0; - for ( axis = 0; axis < naxes; axis++ ) { - -/* Obtain the axis Digits value, using the Frame's Digits value as a - default. */ - ax = astGetAxis( this, invperm[ axis ] ); - set = astTestAxisDigits( ax ); - ival = set ? astGetAxisDigits( ax ) : astGetDigits( this ); - ax = astAnnul( ax ); - -/* Show the value if it is set for the axis (i.e. if it differs from - the default for the whole Frame) and note if any such value is - set. */ - helpful = set; - if ( set ) digits_set = 1; - (void) sprintf( key, "Dig%d", axis + 1 ); - (void) sprintf( comment, "Individual precision for axis %d", - axis + 1 ); - astWriteInt( channel, key, 0, helpful, ival, comment ); - } - -/* There is also a Digits value for the Frame as a whole... */ - set = TestDigits( this, status ); - -/* Show the value (even if not set) if an explicit Digits value has - been set for any axis (above). */ - helpful = digits_set; - ival = set ? GetDigits( this, status ) : astGetDigits( this ); - astWriteInt( channel, "Digits", set, helpful, ival, - "Default formatting precision" ); - -/* Format. */ -/* ------- */ -/* There is a Format value for each axis. */ - for ( axis = 0; axis < naxes; axis++ ) { - sval = astGetFormat( this, invperm[ axis ] ); - -/* Show the Format value if the Digits value is set for an individual - axis. */ - ax = astGetAxis( this, invperm[ axis ] ); - helpful = astTestAxisDigits( ax ); - ax = astAnnul( ax ); - (void) sprintf( key, "Fmt%d", axis + 1 ); - (void) sprintf( comment, "Format specifier for axis %d", axis + 1 ); - astWriteString( channel, key, 0, helpful, sval, comment ); - } - -/* Direction. */ -/* ---------- */ -/* There is a Direction value for each axis. */ - for ( axis = 0; axis < naxes; axis++ ) { - ival = astGetDirection( this, invperm[ axis ] ); - -/* Show the value if it is zero. */ - helpful = ( ival == 0 ); - (void) sprintf( key, "Dir%d", axis + 1 ); - (void) sprintf( comment, - ival ? "Plot axis %d in conventional direction" : - "Plot axis %d in reverse direction", - axis + 1 ); - astWriteInt( channel, key, 0, helpful, ival, comment ); - } - -/* Bottom. */ -/* ------- */ -/* There is a Bottom value for each axis. */ - for ( axis = 0; axis < naxes; axis++ ) { - dval = astGetBottom( this, invperm[ axis ] ); - -/* Show the value if it is zero. */ - helpful = ( dval != -DBL_MAX ); - (void) sprintf( key, "Bot%d", axis + 1 ); - astWriteDouble( channel, key, 0, helpful, dval, "Lowest legal axis value"); - } - -/* Top. */ -/* ------- */ -/* There is a Top value for each axis. */ - for ( axis = 0; axis < naxes; axis++ ) { - dval = astGetTop( this, invperm[ axis ] ); - -/* Show the value if it is zero. */ - helpful = ( dval != DBL_MAX ); - (void) sprintf( key, "Top%d", axis + 1 ); - astWriteDouble( channel, key, 0, helpful, dval, "Highest legal axis value"); - } - -/* PreserveAxes. */ -/* ------------- */ - set = TestPreserveAxes( this, status ); - ival = set ? GetPreserveAxes( this, status ) : astGetPreserveAxes( this ); - astWriteInt( channel, "Presrv", set, 0, ival, - ival ? "Preserve target axes" : - "Don't preserve target axes" ); - -/* Permute. */ -/* -------- */ - set = TestPermute( this, status ); - ival = set ? GetPermute( this, status ) : astGetPermute( this ); - astWriteInt( channel, "Permut", set, 0, ival, - ival ? "Axes may be permuted to match" : - "Axes may not be permuted match" ); - -/* MinAxes. */ -/* -------- */ - set = TestMinAxes( this, status ); - ival = set ? GetMinAxes( this, status ) : astGetMinAxes( this ); - astWriteInt( channel, "MinAx", set, 0, ival, - "Minimum number of axes to match" ); - -/* MaxAxes. */ -/* -------- */ - set = TestMaxAxes( this, status ); - ival = set ? GetMaxAxes( this, status ) : astGetMaxAxes( this ); - astWriteInt( channel, "MaxAx", set, 0, ival, - "Maximum number of axes to match" ); - -/* MatchEnd. */ -/* --------- */ - set = TestMatchEnd( this, status ); - ival = set ? GetMatchEnd( this, status ) : astGetMatchEnd( this ); - astWriteInt( channel, "MchEnd", set, 0, ival, - ival ? "Match final target axes" : - "Match initial target axes" ); - -/* ObsLat. */ -/* ------- */ - set = TestObsLat( this, status ); - dval = set ? GetObsLat( this, status ) : astGetObsLat( this ); - astWriteDouble( channel, "ObsLat", set, 0, dval, "Observers geodetic latitude (rads)" ); - -/* ObsLon. */ -/* ------- */ - set = TestObsLon( this, status ); - dval = set ? GetObsLon( this, status ) : astGetObsLon( this ); - astWriteDouble( channel, "ObsLon", set, 0, dval, "Observers geodetic longitude (rads)" ); - -/* ObsAlt. */ -/* ------- */ - set = TestObsAlt( this, status ); - dval = set ? GetObsAlt( this, status ) : astGetObsAlt( this ); - astWriteDouble( channel, "ObsAlt", set, 0, dval, "Observers geodetic altitude (metres)" ); - -/* Dtai*/ -/* ---- */ - set = TestDtai( this, status ); - dval = set ? GetDtai( this, status ) : astGetDtai( this ); - astWriteDouble( channel, "Dtai", set, 0, dval, "TAI-UTC in seconds" ); - -/* Dut1*/ -/* ---- */ - set = TestDut1( this, status ); - dval = set ? GetDut1( this, status ) : astGetDut1( this ); - astWriteDouble( channel, "Dut1", set, 0, dval, "UT1-UTC in seconds" ); - - -/* ActiveUnit. */ -/* ----------- */ - if( astTestActiveUnit( this ) ) { - ival = astGetActiveUnit( this ); - astWriteInt( channel, "ActUnt", 1, 0, ival, - ival ? "Unit strings affects alignment" : - "Unit strings do not affect alignment" ); - } - -/* Axis permutation array. */ -/* ----------------------- */ -/* Write out the axis permutation array value for each axis, - converting to 1-based axis numbering. */ - for ( axis = 0; axis < this->naxes; axis++ ) { - set = ( this->perm[ axis ] != axis ); - ival = this->perm[ axis ] + 1; - -/* Create a keyword and comment appropriate to the axis. */ - (void) sprintf( key, "Prm%d", axis + 1 ); - if ( set ) { - (void) sprintf( comment, - "Axis %d permuted to use internal axis %d", - axis + 1, ival ); - } else { - (void) sprintf( comment, "Axis %d not permuted", axis + 1 ); - } - astWriteInt( channel, key, set, 0, ival, comment ); - } - -/* Axis Objects. */ -/* ------------- */ -/* Temporarily set the Channel's Full attribute to -1 (unless it is +1 - to start with), remembering the original setting. This prevents any - unnecessary "un-set" Axis values being output that would otherwise - simply duplicate the Frame's attributes which have already been - written. "Set" Axis values are still written, however (and all - values are written if Full is set to 1). */ - full_set = astTestFull( channel ); - full = astGetFull( channel ); - if ( full <= 0 ) astSetFull( channel, -1 ); - -/* Handle each axis in turn. */ - for ( axis = 0; axis < this->naxes; axis++ ) { - -/* Create a keyword and comment appropriate to the axis (converting to - 1-based axis numbering). */ - (void) sprintf( key, "Ax%d", axis + 1 ); - (void) sprintf( comment, "Axis number %d", axis + 1 ); - -/* Write out the axis Object description. */ - astWriteObject( channel, key, 1, 0, this->axis[ axis ], comment ); - } - -/* Restore the Channel's original Full attribute setting. */ - if ( full_set ) { - astSetFull( channel, full ); - } else { - astClearFull( channel ); - } - -/* Free the inverse axis permutation array. */ - invperm = astFree( invperm ); - -/* Variants */ -/* ------- */ - if( this->variants ) astWriteObject( channel, "Vrnts", 1, 0, - this->variants, "Variant Frames" ); - } - -/* Undefine macros local to this function. */ -#undef COMMENT_LEN -#undef KEY_LEN -} - -/* Standard class functions. */ -/* ========================= */ -/* Implement the astIsAFrame and astCheckFrame functions using the macros - defined for this purpose in the "object.h" header file. */ -astMAKE_ISA(Frame,Mapping) -astMAKE_CHECK(Frame) - -AstFrame *astFrame_( int naxes, const char *options, int *status, ...) { -/* -*+ -* Name: -* astFrame - -* Purpose: -* Create a Frame. - -* Type: -* Protected function. - -* Synopsis: -* #include "frame.h" -* AstFrame *astFrame( int naxes, const char *options, int *status, ... ) - -* Class Membership: -* Frame constructor. - -* Description: -* This function creates a new Frame and optionally initialises its -* attributes. - -* Parameters: -* naxes -* The number of Frame axes. -* options -* Pointer to a null terminated string containing an optional -* comma-separated list of attribute assignments to be used for -* initialising the new Frame. The syntax used is the same as -* for the astSet method and may include "printf" format -* specifiers identified by "%" symbols in the normal way. -* status -* Pointer to the inherited status variable. -* ... -* If the "options" string contains "%" format specifiers, then -* an optional list of arguments may follow it in order to -* supply values to be substituted for these specifiers. The -* rules for supplying these are identical to those for the -* astSet method (and for the C "printf" function). - -* Returned Value: -* A pointer to the new 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. -*- - -* Implementation Notes: -* - This function implements the basic Frame constructor which is -* available via the protected interface to the Frame class. A -* public interface is provided by the astFrameId_ function. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Pointer to thread-specific global data */ - AstFrame *new; /* Pointer to new Frame */ - va_list args; /* Variable argument list */ - -/* Get a pointer to the thread specific global data structure. */ - astGET_GLOBALS(NULL); - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Initialise the Frame, allocating memory and initialising the virtual - function table as well if necessary. */ - new = astInitFrame( NULL, sizeof( AstFrame ), !class_init, &class_vtab, - "Frame", naxes ); - -/* If successful, note that the virtual function table has been initialised. */ - if ( astOK ) { - class_init = 1; - -/* Obtain the variable argument list and pass it along with the options string - to the astVSet method to initialise the new Frame's attributes. */ - va_start( args, status ); - astVSet( new, options, NULL, args ); - va_end( args ); - -/* If an error occurred, clean up by deleting the new object. */ - if ( !astOK ) new = astDelete( new ); - } - -/* Return a pointer to the new Frame. */ - return new; -} - -AstFrame *astInitFrame_( void *mem, size_t size, int init, - AstFrameVtab *vtab, const char *name, - int naxes, int *status ) { -/* -*+ -* Name: -* astInitFrame - -* Purpose: -* Initialise a Frame. - -* Type: -* Protected function. - -* Synopsis: -* #include "frame.h" -* AstFrame *astInitFrame( void *mem, size_t size, int init, -* AstFrameVtab *vtab, const char *name, -* int naxes ) - -* Class Membership: -* Frame initialiser. - -* Description: -* This function is provided for use by class implementations to initialise -* a new Frame object. It allocates memory (if necessary) to accommodate -* the Frame plus any additional data associated with the derived class. -* It then initialises a Frame 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 Frame at the start of the memory passed via the -* "vtab" parameter. - -* Parameters: -* mem -* A pointer to the memory in which the Frame is to be created. This -* must be of sufficient size to accommodate the Frame data -* (sizeof(Frame)) 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 Frame (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 Frame -* structure, so a valid value must be supplied even if not required for -* allocating memory. -* init -* A logical flag indicating if the Frame'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 Frame. -* 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). -* naxes -* The number of Frame axes. - -* Returned Value: -* A pointer to the new 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. -*- -*/ - -/* Local Variables: */ - AstFrame *new; /* Pointer to new Frame */ - int axis; /* Loop counter for Frame axes */ - -/* Check the global status. */ - if ( !astOK ) return NULL; - -/* If necessary, initialise the virtual function table. */ - if ( init ) astInitFrameVtab( vtab, name ); - -/* Initialise. */ - new = NULL; - -/* Check the number of axes for validity, reporting an error if necessary. */ - if ( naxes < 0 ) { - astError( AST__NAXIN, "astInitFrame(%s): Number of axes (%d) is " - "invalid - this number should not be negative.", status, name, naxes ); - -/* Initialise a Mapping structure (the parent class) as the first - component within the Frame structure, allocating memory if - necessary. Set the number of input/output coordinates to zero (the - astGetNin and astGetNout methods are over-ridden by the Frame class - to provide values for these that are equal to the number of Frame - axes). */ - } else { - new = (AstFrame *) astInitMapping( mem, size, 0, - (AstMappingVtab *) vtab, name, - 0, 0, 1, 1 ); - - if ( astOK ) { - -/* Initialise the Frame data. */ -/* ----------------------------- */ -/* Set the number of Frame axes. */ - new->naxes = naxes; - -/* Initialise all attributes to their "undefined" values. */ - new->digits = -INT_MAX; - new->domain = NULL; - new->epoch = AST__BAD; - new->match_end = -INT_MAX; - new->max_axes = -INT_MAX; - new->min_axes = -INT_MAX; - new->permute = -INT_MAX; - new->preserve_axes = -INT_MAX; - new->title = NULL; - new->system = AST__BADSYSTEM; - new->alignsystem = AST__BADSYSTEM; - new->active_unit = -INT_MAX; - new->obsalt = AST__BAD; - new->obslat = AST__BAD; - new->obslon = AST__BAD; - new->dtai = AST__BAD; - new->dut1 = AST__BAD; - new->flags = 0; - new->variants = NULL; - -/* Allocate memory to store pointers to the Frame's Axis objects and to store - its axis permutation array. */ - new->axis = astMalloc( sizeof( AstAxis * ) * (size_t) naxes ); - new->perm = astMalloc( sizeof( int ) * (size_t) naxes ); - -/* Create a new Axis object to describe each axis of the Frame and store the - resulting pointers in the memory allocated above. Also initialise the - axis permutation array so that the axes appear in their natural order. */ - if ( astOK ) { - for ( axis = 0; axis < naxes; axis++ ) { - new->axis[ axis ] = astAxis( "", status ); - new->perm[ axis ] = axis; - } - -/* If an error occurred while creating the Axis objects, scan through the array - of pointers to them again to ensure that they are all correctly annulled. */ - if ( !astOK ) { - for ( axis = 0; axis < naxes; axis++ ) { - new->axis[ axis ] = astAnnul( new->axis[ axis ] ); - } - } - } - -/* 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; -} - -AstFrame *astLoadFrame_( void *mem, size_t size, - AstFrameVtab *vtab, const char *name, - AstChannel *channel, int *status ) { -/* -*+ -* Name: -* astLoadFrame - -* Purpose: -* Load a Frame. - -* Type: -* Protected function. - -* Synopsis: -* #include "frame.h" -* AstFrame *astLoadFrame( void *mem, size_t size, -* AstFrameVtab *vtab, const char *name, -* AstChannel *channel ) - -* Class Membership: -* Frame loader. - -* Description: -* This function is provided to load a new Frame 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 -* Frame structure in this memory, using data read from the input -* Channel. -* -* If the "init" flag is set, it also initialises the contents of a -* virtual function table for a Frame at the start of the memory -* passed via the "vtab" parameter. - - -* Parameters: -* mem -* A pointer to the memory into which the Frame is to be loaded. -* This must be of sufficient size to accommodate the Frame data -* (sizeof(Frame)) 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 Frame (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 Frame 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(AstFrame) is used instead. -* vtab -* Pointer to the start of the virtual function table to be -* associated with the new Frame. If this is NULL, a pointer to -* the (static) virtual function table for the Frame 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 "Frame" is used instead. - -* Returned Value: -* A pointer to the new 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. -*- -*/ - -/* Local Constants: */ - astDECLARE_GLOBALS /* Pointer to thread-specific global data */ -#define KEY_LEN 50 /* Maximum length of a keyword */ - -/* Local Variables: */ - AstFrame *new; /* Pointer to the new Frame */ - char *sval; /* Pointer to string value */ - char key[ KEY_LEN + 1 ]; /* Buffer for keywords */ - double dval; /* DOuble attribute value */ - int axis; /* Loop counter for axes */ - int ival; /* Integer value */ - -/* 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 Frame. In this case the - Frame belongs to this class, so supply appropriate values to be - passed to the parent class loader (and its parent, etc.). */ - if ( !vtab ) { - size = sizeof( AstFrame ); - vtab = &class_vtab; - name = "Frame"; - -/* If required, initialise the virtual function table for this class. */ - if ( !class_init ) { - astInitFrameVtab( 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 Frame. */ - new = astLoadMapping( mem, size, (AstMappingVtab *) vtab, name, - channel ); - - if ( astOK ) { - -/* Assign values for transient components that are not included in the - Frame dump */ - new->flags = 0; - -/* Read input data. */ -/* ================ */ -/* Request the input Channel to read all the input data appropriate to - this class into the internal "values list". */ - astReadClassData( channel, "Frame" ); - -/* 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. */ - -/* Naxes. */ -/* ------ */ -/* Obtain the number of Frame axes and allocate memory for the arrays - which hold axis information. */ - new->naxes = astReadInt( channel, "naxes", 0 ); - if ( new->naxes < 0 ) new->naxes = 0; - new->perm = astMalloc( sizeof( int ) * (size_t) new->naxes ); - new->axis = astMalloc( sizeof( AstAxis * ) * (size_t) new->naxes ); - -/* If an error occurred, ensure that any allocated memory is freed. */ - if ( !astOK ) { - new->perm = astFree( new->perm ); - new->axis = astFree( new->axis ); - -/* Otherwise, initialise the array of Axis pointers. */ - } else { - for ( axis = 0; axis < new->naxes; axis++ ) new->axis[ axis ] = NULL; - -/* Now obtain those input values which are required for each axis... */ - for ( axis = 0; axis < new->naxes; axis++ ) { - -/* Axis object. */ -/* ------------ */ -/* This must be read first, so that it can hold the other axis values - obtained below. */ - -/* Create a keyword appropriate to this axis. */ - (void) sprintf( key, "ax%d", axis + 1 ); - -/* Read the Axis object. If none was read, provide a default Axis - instead. */ - new->axis[ axis ] = astReadObject( channel, key, NULL ); - if ( !new->axis[ axis ] ) new->axis[ axis ] = astAxis( "", status ); - -/* Label. */ -/* ------ */ -/* Read the Label string for each axis. If a value is obtained, use - it to set the Label attribute for the axis. Free the memory holding - the string when no longer needed. */ - (void) sprintf( key, "lbl%d", axis + 1 ); - sval = astReadString( channel, key, NULL ); - if ( sval ) { - astSetAxisLabel( new->axis[ axis ], sval ); - sval = astFree( sval ); - } - -/* Symbol. */ -/* ------- */ - (void) sprintf( key, "sym%d", axis + 1 ); - sval = astReadString( channel, key, NULL ); - if ( sval ) { - astSetAxisSymbol( new->axis[ axis ], sval ); - sval = astFree( sval ); - } - -/* Format. */ -/* ------- */ - (void) sprintf( key, "fmt%d", axis + 1 ); - sval = astReadString( channel, key, NULL ); - if ( sval ) { - astSetAxisFormat( new->axis[ axis ], sval ); - sval = astFree( sval ); - } - -/* Unit. */ -/* ----- */ - (void) sprintf( key, "uni%d", axis + 1 ); - sval = astReadString( channel, key, NULL ); - if ( sval ) { - astSetAxisUnit( new->axis[ axis ], sval ); - sval = astFree( sval ); - } - -/* Direction. */ -/* ---------- */ - (void) sprintf( key, "dir%d", axis + 1 ); - ival = astReadInt( channel, key, -INT_MAX ); - if ( ival != -INT_MAX ) { - astSetAxisDirection( new->axis[ axis ], ival ); - } - -/* Top. */ -/*----- */ - (void) sprintf( key, "top%d", axis + 1 ); - dval = astReadDouble( channel, key, AST__BAD ); - if ( dval != AST__BAD ) { - astSetAxisTop( new->axis[ axis ], dval ); - } - -/* Bottom. */ -/*----- -- */ - (void) sprintf( key, "bot%d", axis + 1 ); - dval = astReadDouble( channel, key, AST__BAD ); - if ( dval != AST__BAD ) { - astSetAxisBottom( new->axis[ axis ], dval ); - } - -/* Digits. */ -/* ------- */ - (void) sprintf( key, "dig%d", axis + 1 ); - ival = astReadInt( channel, key, -INT_MAX ); - if ( ival != -INT_MAX ) { - astSetAxisDigits( new->axis[ axis ], ival ); - } - -/* Axis permutation array. */ -/* ----------------------- */ -/* Convert from 1-based to zero-based axis numbering at this - point. The default is the "un-permuted" value. */ - sprintf( key, "prm%d", axis + 1 ); - new->perm[ axis ] = astReadInt( channel, key, axis + 1 ) - 1; - -/* Quit looping if an error occurs. */ - if ( !astOK ) break; - } - -/* The remaining values are not associated with particular axes... */ - -/* Title. */ -/* ------ */ - new->title = astReadString( channel, "title", NULL ); - -/* Domain. */ -/* ------- */ - new->domain = astReadString( channel, "domain", NULL ); - -/* Epoch. */ -/* ------ */ -/* Interpret this as Besselian or Julian depending on its value. */ - new->epoch = astReadDouble( channel, "epoch", AST__BAD ); - if ( TestEpoch( new, status ) ) { - SetEpoch( new, ( new->epoch < 1984.0 ) ? palEpb2d( new->epoch ) : - palEpj2d( new->epoch ), status ); - } - -/* Digits. */ -/* ------- */ -/* This is the value that applies to the Frame as a whole. */ - new->digits = astReadInt( channel, "digits", -INT_MAX ); - if ( TestDigits( new, status ) ) SetDigits( new, new->digits, status ); - -/* PreserveAxes. */ -/* ------------- */ - new->preserve_axes = astReadInt( channel, "presrv", -INT_MAX ); - if ( TestPreserveAxes( new, status ) ) { - SetPreserveAxes( new, new->preserve_axes, status ); - } - -/* Permute. */ -/* -------- */ - new->permute = astReadInt( channel, "permut", -INT_MAX ); - if ( TestPermute( new, status ) ) SetPermute( new, new->permute, status ); - -/* MinAxes. */ -/* -------- */ - new->min_axes = astReadInt( channel, "minax", -INT_MAX ); - if ( TestMinAxes( new, status ) ) SetMinAxes( new, new->min_axes, status ); - -/* MaxAxes. */ -/* -------- */ - new->max_axes = astReadInt( channel, "maxax", -INT_MAX ); - if ( TestMaxAxes( new, status ) ) SetMaxAxes( new, new->max_axes, status ); - -/* MatchEnd. */ -/* --------- */ - new->match_end = astReadInt( channel, "mchend", -INT_MAX ); - if ( TestMatchEnd( new, status ) ) SetMatchEnd( new, new->match_end, status ); - -/* ObsLat. */ -/* ------- */ - new->obslat = astReadDouble( channel, "obslat", AST__BAD ); - if ( TestObsLat( new, status ) ) SetObsLat( new, new->obslat, status ); - -/* ObsLon. */ -/* ------- */ - new->obslon = astReadDouble( channel, "obslon", AST__BAD ); - if ( TestObsLon( new, status ) ) SetObsLon( new, new->obslon, status ); - -/* ObsAlt. */ -/* ------- */ - new->obsalt = astReadDouble( channel, "obsalt", AST__BAD ); - if ( TestObsAlt( new, status ) ) SetObsAlt( new, new->obsalt, status ); - -/* Dtai. */ -/* ---- */ - new->dtai = astReadDouble( channel, "dtai", AST__BAD ); - if ( TestDtai( new, status ) ) SetDtai( new, new->dtai, status ); - -/* Dut1. */ -/* ---- */ - new->dut1 = astReadDouble( channel, "dut1", AST__BAD ); - if ( TestDut1( new, status ) ) SetDut1( new, new->dut1, status ); - -/* ActiveUnit. */ -/* ----------- */ - new->active_unit = astReadInt( channel, "actunt", -INT_MAX ); - if ( TestActiveUnit( new, status ) ) SetActiveUnit( new, new->active_unit, status ); - -/* System. */ -/* ------- */ -/* Set the default and read the external representation as a string. */ - new->system = AST__BADSYSTEM; - sval = astReadString( channel, "system", NULL ); - -/* If a value was read, convert from a string to a System code. */ - if ( sval ) { - if ( astOK ) { - new->system = astSystemCode( new, sval ); - -/* Report an error if the value wasn't recognised. */ - if ( new->system == AST__BADSYSTEM ) { - astError( AST__ATTIN, - "astRead(%s): Invalid System description " - "\"%s\".", status, astGetClass( channel ), sval ); - } - } - -/* Free the string value. */ - sval = astFree( sval ); - } - -/* AlignSystem. */ -/* ------------ */ -/* Set the default and read the external representation as a string. */ - new->alignsystem = AST__BADSYSTEM; - sval = astReadString( channel, "alsys", NULL ); - -/* If a value was read, convert from a string to a System code. */ - if ( sval ) { - if ( astOK ) { - new->alignsystem = astSystemCode( new, sval ); - -/* Report an error if the value wasn't recognised. */ - if ( new->alignsystem == AST__BADSYSTEM ) { - astError( AST__ATTIN, - "astRead(%s): Invalid AlignSystem description " - "\"%s\".", status, astGetClass( channel ), sval ); - } - } - -/* Free the string value. */ - sval = astFree( sval ); - } - -/* Variants. */ -/* -------- */ - new->variants = astReadObject( channel, "vrnts", NULL ); - } - -/* If an error occurred, clean up by deleting the new Frame. */ - if ( !astOK ) new = astDelete( new ); - } - -/* Return the new Frame 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. */ -const char *astAbbrev_( AstFrame *this, int axis, const char *fmt, - const char *str1, const char *str2, int *status ) { - if ( !astOK ) return str2; - return (**astMEMBER(this,Frame,Abbrev))( this, axis, fmt, str1, str2, status ); -} -int astFields_( AstFrame *this, int axis, const char *fmt, - const char *str, int maxfld, char **fields, - int *nc, double *val, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,Fields))( this, axis, fmt, str, maxfld, fields, nc, val, status ); -} -void astCheckPerm_( AstFrame *this, const int *perm, const char *method, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,CheckPerm))( this, perm, method, status ); -} - -AstPointSet *astResolvePoints_( AstFrame *this, const double point1[], - const double point2[], AstPointSet *in, - AstPointSet *out, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,ResolvePoints))( this, point1, point2, in, out, status ); -} -AstLineDef *astLineDef_( AstFrame *this, const double start[2], - const double end[2], int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,LineDef))( this, start, end, status ); -} -int astLineCrossing_( AstFrame *this, AstLineDef *l1, AstLineDef *l2, - double **cross, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,LineCrossing))( this, l1, l2, cross, status ); -} -void astLineOffset_( AstFrame *this, AstLineDef *line, double par, double prp, - double point[2], int *status ){ - if ( !astOK ) return; - (**astMEMBER(this,Frame,LineOffset))( this, line, par, prp, point, status ); -} -int astLineContains_( AstFrame *this, AstLineDef *l, int def, double *point, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,LineContains))( this, l, def, point, status ); -} -AstFrameSet *astConvert_( AstFrame *from, AstFrame *to, - const char *domainlist, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(from,Frame,Convert))( from, to, domainlist, status ); -} -AstFrameSet *astConvertX_( AstFrame *to, AstFrame *from, - const char *domainlist, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(to,Frame,ConvertX))( to, from, domainlist, status ); -} -double astAngle_( AstFrame *this, const double a[], const double b[], - const double c[], int *status ) { - if ( !astOK ) return AST__BAD; - return (**astMEMBER(this,Frame,Angle))( this, a, b, c, status ); -} -int astGetActiveUnit_( AstFrame *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,GetActiveUnit))( this, status ); -} -int astTestActiveUnit_( AstFrame *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,TestActiveUnit))( this, status ); -} -void astSetActiveUnit_( AstFrame *this, int value, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,SetActiveUnit))( this, value, status ); -} -double astDistance_( AstFrame *this, - const double point1[], const double point2[], int *status ) { - if ( !astOK ) return AST__BAD; - return (**astMEMBER(this,Frame,Distance))( this, point1, point2, status ); -} -AstFrameSet *astFindFrame_( AstFrame *target, AstFrame *template, - const char *domainlist, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(target,Frame,FindFrame))( target, template, domainlist, status ); -} -void astMatchAxes_( AstFrame *frm1, AstFrame *frm2, int *axes, int *status ) { - if ( !astOK ) return; - (**astMEMBER(frm1,Frame,MatchAxes))( frm1, frm2, axes, status ); -} -void astMatchAxesX_( AstFrame *frm2, AstFrame *frm1, int *axes, int *status ) { - if ( !astOK ) return; - (**astMEMBER(frm2,Frame,MatchAxesX))( frm2, frm1, axes, status ); -} -const char *astFormat_( AstFrame *this, int axis, double value, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,Format))( this, axis, value, status ); -} -double astCentre_( AstFrame *this, int axis, double value, double gap, int *status ) { - if ( !astOK ) return 0.0; - return (**astMEMBER(this,Frame,Centre))( this, axis, value, gap, status ); -} -double astGap_( AstFrame *this, int axis, double gap, int *ntick, int *status ) { - if ( !astOK ) return 0.0; - return (**astMEMBER(this,Frame,Gap))( this, axis, gap, ntick, status ); -} -AstAxis *astGetAxis_( AstFrame *this, int axis, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,GetAxis))( this, axis, status ); -} -int astGetNaxes_( AstFrame *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,GetNaxes))( this, status ); -} -const int *astGetPerm_( AstFrame *this, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,GetPerm))( this, status ); -} -AstFrameSet *astGetFrameVariants_( AstFrame *this, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,GetFrameVariants))( this, status ); -} -void astSetFrameVariants_( AstFrame *this, AstFrameSet *variants, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,SetFrameVariants))( this, variants, status ); -} - - -int astMatch_( AstFrame *this, AstFrame *target, int matchsub, - int **template_axes, int **target_axes, - AstMapping **map, AstFrame **result, int *status ) { - - AstFrame *super_this; - const char *dom; - int match; - - if ( !astOK ) return 0; - - match = (**astMEMBER(this,Frame,Match))( this, target, matchsub, - template_axes, target_axes, - map, result, status ); - -/* If the template ("this") could not be used to probe the target, it may - be because the template class is a more specialised form of the target - class. E.g. a SkyFrame cannot directly be used to probe a Frame, but a - Frame *can* be used to probe a SkyFrame. This means (for instance), - that a basic Frame with Domain FRED cannot be aligned (using astConvert) - with a CmpFrame with Domain FRED. This sort of alignment is often - useful, so we try now to use the supplied template to probe a modified - form of the target that has been cast into the same class as the - template. This is only possible if the template class is a sub-class of - the target class. Attempt to do the cast. */ - if( ! match && matchsub ) { - super_this = (AstFrame *) astCast( this, target ); - -/* If the cast was possible, fix the template Domain since the parent - class may provide a different default Domain, and then invoke the Match - method appropriate to the new template class (i.e. the target class). */ - if( super_this ) { - if( astTestDomain( target ) ) { - dom = astGetDomain( this ); - if( astChrLen( dom ) > 0 ) astSetDomain( super_this, dom ); - } - match = (**astMEMBER(super_this,Frame,Match))( super_this, target, - matchsub, template_axes, - target_axes, map, - result, status ); - super_this = astAnnul( super_this ); - } - } - - return match; -} - - -int astIsUnitFrame_( AstFrame *this, int *status ){ - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,IsUnitFrame))( this, status ); -} -void astNorm_( AstFrame *this, double value[], int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,Norm))( this, value, status ); -} -void astNormBox_( AstFrame *this, double lbnd[], double ubnd[], AstMapping *reg, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,NormBox))( this, lbnd, ubnd, reg, status ); -} -double astAxDistance_( AstFrame *this, int axis, double v1, double v2, int *status ) { - if ( !astOK ) return AST__BAD; - return (**astMEMBER(this,Frame,AxDistance))( this, axis, v1, v2, status ); -} -void astAxNorm_( AstFrame *this, int axis, int oper, int nval, double *values, - int *status ){ - if ( !astOK ) return; - return (**astMEMBER(this,Frame,AxNorm))( this, axis, oper, nval, values, status ); -} -double astAxOffset_( AstFrame *this, int axis, double v1, double dist, int *status ) { - if ( !astOK ) return AST__BAD; - return (**astMEMBER(this,Frame,AxOffset))( this, axis, v1, dist, status ); -} - - -AstPointSet *astFrameGrid_( AstFrame *this, int size, const double *lbnd, - const double *ubnd, int *status ){ - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,FrameGrid))( this, size, lbnd, ubnd, status ); -} - - -void astOffset_( AstFrame *this, const double point1[], const double point2[], - double offset, double point3[], int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,Offset))( this, point1, point2, offset, point3, status ); -} -double astAxAngle_( AstFrame *this, const double a[2], const double b[2], - int axis, int *status ) { - if ( !astOK ) return AST__BAD; - return (**astMEMBER(this,Frame,AxAngle))( this, a, b, axis, status ); -} -double astOffset2_( AstFrame *this, const double point1[2], double angle, - double offset, double point2[2], int *status ) { - if ( !astOK ) return AST__BAD; - return (**astMEMBER(this,Frame,Offset2))( this, point1, angle, offset, point2, status ); -} -void astIntersect_( AstFrame *this, const double a1[2], - const double a2[2], const double b1[2], - const double b2[2], double cross[2], - int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,Intersect))( this, a1, a2, b1, b2, cross, status ); -} -void astOverlay_( AstFrame *template, const int *template_axes, - AstFrame *result, int *status ) { - if ( !astOK ) return; - (**astMEMBER(template,Frame,Overlay))( template, template_axes, result, status ); -} -void astPermAxes_( AstFrame *this, const int perm[], int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,PermAxes))( this, perm, status ); -} -AstFrame *astPickAxes_( AstFrame *this, int naxes, const int axes[], - AstMapping **map, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,PickAxes))( this, naxes, axes, map, status ); -} -void astPrimaryFrame_( AstFrame *this, int axis1, - AstFrame **frame, int *axis2, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,PrimaryFrame))( this, axis1, frame, axis2, status ); -} -void astResolve_( AstFrame *this, const double point1[], const double point2[], - const double point3[], double point4[], double *d1, - double *d2, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,Resolve))( this, point1, point2, point3, point4, d1, d2, status ); -} -void astSetAxis_( AstFrame *this, int axis, AstAxis *newaxis, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,SetAxis))( this, axis, newaxis, status ); -} -void astSetUnit_( AstFrame *this, int axis, const char *value, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,SetUnit))( this, axis, value, status ); -} -void astClearUnit_( AstFrame *this, int axis, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,ClearUnit))( this, axis, status ); -} -int astSubFrame_( AstFrame *target, AstFrame *template, int result_naxes, - const int *target_axes, const int *template_axes, - AstMapping **map, AstFrame **result, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(target,Frame,SubFrame))( target, template, result_naxes, - target_axes, template_axes, - map, result, status ); -} -int astUnformat_( AstFrame *this, int axis, const char *string, - double *value, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,Unformat))( this, axis, string, value, status ); -} -int astValidateAxis_( AstFrame *this, int axis, int fwd, const char *method, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,ValidateAxis))( this, axis, fwd, method, status ); -} -void astValidateAxisSelection_( AstFrame *this, int naxes, const int *axes, - const char *method, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,ValidateAxisSelection))( this, naxes, axes, - method, status ); -} -AstSystemType astValidateSystem_( AstFrame *this, AstSystemType system, const char *method, int *status ) { - if ( !astOK ) return AST__BADSYSTEM; - return (**astMEMBER(this,Frame,ValidateSystem))( this, system, method, status ); -} -AstSystemType astSystemCode_( AstFrame *this, const char *system, int *status ) { - if ( !astOK ) return AST__BADSYSTEM; - return (**astMEMBER(this,Frame,SystemCode))( this, system, status ); -} -const char *astSystemString_( AstFrame *this, AstSystemType system, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,Frame,SystemString))( this, system, status ); -} -int astAxIn_( AstFrame *this, int axis, double lo, double hi, double val, - int closed, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,AxIn))( this, axis, lo, hi, val, closed, status ); -} -int astGetFrameFlags_( AstFrame *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,Frame,GetFrameFlags))( this, status ); -} -void astSetFrameFlags_( AstFrame *this, int value, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,Frame,SetFrameFlags))( this, value, status ); -} - - -/* 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. */ -AstFrame *PickAxesId_( AstFrame *, int, const int[], AstMapping **, int * ); -AstFrame *astFrameId_( int, const char *, ... ); -const char *astFormatId_( AstFrame *, int, double, int * ); -int astUnformatId_( AstFrame *, int, const char *, double *, int * ); -void astPermAxesId_( AstFrame *, const int[], int * ); - -/* Special interface function implementations. */ -/* ------------------------------------------- */ -const char *astFormatId_( AstFrame *this, int axis, double value, int *status ) { -/* -*++ -* Name: -c astFormat -f AST_FORMAT - -* Purpose: -* Format a coordinate value for a Frame axis. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c const char *astFormat( AstFrame *this, int axis, double value ) -f RESULT = AST_FORMAT( THIS, AXIS, VALUE, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function returns a pointer to a string containing the -f This function returns a character string containing the -* formatted (character) version of a coordinate value for a Frame -* axis. The formatting applied is determined by the Frame's -* attributes and, in particular, by any Format attribute string -* that has been set for the axis. A suitable default format (based -* on the Digits attribute value) will be applied if necessary. - -* Parameters: -c this -f THIS = INTEGER (given) -* Pointer to the Frame. -c axis -f AXIS = INTEGER (Given) -* The number of the Frame axis for which formatting is to be -* performed (axis numbering starts at 1 for the first axis). -c value -f VALUE = DOUBLE PRECISION (Given) -* The coordinate value to be formatted. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astFormat() -c A pointer to a null-terminated string containing the formatted -c value. -f AST_FORMAT = CHARACTER * ( AST__SZCHR ) -f The formatted value. - -* Notes: -c - The returned pointer is guaranteed to remain valid and the -c string to which it points will not be over-written for a total -c of 50 successive invocations of this function. After this, the -c memory containing the string may be re-used, so a copy of the -c string should be made if it is needed for longer than this. -c - A formatted value may be converted back into a numerical (double) -c value using astUnformat. -f - A formatted value may be converted back into a numerical -f (double precision) value using AST_UNFORMAT. -c - A NULL pointer will be returned if this function is invoked -c with the AST error status set, or if it should fail for any -c reason. -f - A blank string will be returned if this function is invoked -f with STATUS set to an error value, or if it should fail for any -f reason. -*-- - -* Implementation Notes: -* This function implements the public interface for the astFormat -* method. It is identical to astFormat_ except that: -* -* - The axis index is decremented by 1 before use. This allows the -* public interface to use 1-based axis numbers (whereas internally -* axis numbers are zero-based). -* -* - The returned string value is buffered in dynamically allocated -* memory so that it will remain valid for a guaranteed number of -* function invocations. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Thread-specific global data */ - const char *fvalue; /* Pointer to formatted value */ - const char *result; /* Pointer value to return */ - int i; /* Loop counter for initialisation */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get a pointer to Thread-specific global data. */ - astGET_GLOBALS(this); - -/* If the "astformatid_strings" array has not been initialised, fill it with NULL - pointers. */ - if ( !astformatid_init ) { - astformatid_init = 1; - for ( i = 0; i < ASTFORMATID_MAX_STRINGS; i++ ) astformatid_strings[ i ] = NULL; - } - -/* Invoke the normal astFormat_ function to obtain a pointer to the - required formatted value, adjusting the axis index to become - zero-based. */ - fvalue = astFormat( this, axis - 1, value ); - -/* If OK, store a copy of the resulting string in dynamically allocated memory, - putting a pointer to the copy into the next element of the "astformatid_strings" - array. (This process also de-allocates any previously allocated memory pointed - at by this "astformatid_strings" element, so the earlier string is effectively - replaced by the new one.) */ - if ( astOK ) { - astBeginPM; - astformatid_strings[ astformatid_istr ] = astStore( astformatid_strings[ astformatid_istr ], fvalue, - strlen( fvalue ) + (size_t) 1 ); - astEndPM; - -/* If OK, return a pointer to the copy and increment "astformatid_istr" to use - the next element of "astformatid_strings" on the next invocation. Recycle - "astformatid_istr" to zero when all elements have been used. */ - if ( astOK ) { - result = astformatid_strings[ astformatid_istr++ ]; - if ( astformatid_istr == ( ASTFORMATID_MAX_STRINGS - 1 ) ) astformatid_istr = 0; - } - } - -/* Return the result. */ - return result; - -} - -AstFrame *astFrameId_( int naxes, const char *options, ... ) { -/* -*++ -* Name: -c astFrame -f AST_FRAME - -* Purpose: -* Create a Frame. - -* Type: -* Public function. - -* Synopsis: -c #include "frame.h" -c AstFrame *astFrame( int naxes, const char *options, ... ) -f RESULT = AST_FRAME( NAXES, OPTIONS, STATUS ) - -* Class Membership: -* Frame constructor. - -* Description: -* This function creates a new Frame and optionally initialises its -* attributes. -* -* A Frame is used to represent a coordinate system. It does this -* in rather the same way that a frame around a graph describes the -* coordinate space in which data are plotted. Consequently, a -* Frame has a Title (string) attribute, which describes the -* coordinate space, and contains axes which in turn hold -* information such as Label and Units strings which are used for -* labelling (e.g.) graphical output. In general, however, the -* number of axes is not restricted to two. -* -* Functions are available for converting Frame coordinate values -* into a form suitable for display, and also for calculating -* distances and offsets between positions within the Frame. -* -* Frames may also contain knowledge of how to transform to and -* from related coordinate systems. - -* Parameters: -c naxes -f NAXES = INTEGER (Given) -* The number of Frame axes (i.e. the number of dimensions of -* the coordinate space which the Frame describes). -c options -f OPTIONS = CHARACTER * ( * ) (Given) -c Pointer to a null-terminated string containing an optional -c comma-separated list of attribute assignments to be used for -c initialising the new Frame. The syntax used is identical to -c that for the astSet function and may include "printf" format -c specifiers identified by "%" symbols in the normal way. -c If no initialisation is required, a zero-length string may be -c supplied. -f A character string containing an optional comma-separated -f list of attribute assignments to be used for initialising the -f new Frame. The syntax used is identical to that for the -f AST_SET routine. If no initialisation is required, a blank -f value may be supplied. -c ... -c If the "options" string contains "%" format specifiers, then -c an optional list of additional arguments may follow it in -c order to supply values to be substituted for these -c specifiers. The rules for supplying these are identical to -c those for the astSet function (and for the C "printf" -c function). -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astFrame() -f AST_FRAME = INTEGER -* A pointer to the new Frame. - -* Examples: -c frame = astFrame( 2, "Title=Energy Spectrum: Plot %d", n ); -c Creates a new 2-dimensional Frame and initialises its Title -c attribute to the string "Energy Spectrum: Plot <n>", where -c <n> takes the value of the int variable "n". -c frame = astFrame( 2, "Label(1)=Energy, Label(2)=Response" ); -c Creates a new 2-dimensional Frame and initialises its axis -c Label attributes to suitable string values. -f FRAME = AST_FRAME( 2, 'Title=Energy Spectrum', STATUS ); -f Creates a new 2-dimensional Frame and initialises its Title -f attribute to the string "Energy Spectrum". -f FRAME = AST_FRAME( 2, 'Label(1)=Energy, Label(2)=Response', STATUS ); -f Creates a new 2-dimensional Frame and initialises its axis -f Label attributes to suitable string values. - -* 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. -*-- - -* Implementation Notes: -* - This function implements the external (public) interface to -* the astFrame constructor function. It returns an ID value -* (instead of a true C pointer) to external users, and must be -* provided because astFrame_ has a variable argument list which -* cannot be encapsulated in a macro (where this conversion would -* otherwise occur). -* - The variable argument list also prevents this function from -* invoking astFrame_ directly, so it must be a re-implementation -* of it in all respects, except for the final conversion of the -* result to an ID value. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Pointer to thread-specific global data */ - AstFrame *new; /* Pointer to new Frame */ - va_list args; /* Variable argument list */ - - int *status; /* Pointer to inherited status value */ - -/* Get a pointer to the inherited status value. */ - status = astGetStatusPtr; - -/* Get a pointer to the thread specific global data structure. */ - astGET_GLOBALS(NULL); - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Initialise the Frame, allocating memory and initialising the virtual - function table as well if necessary. */ - new = astInitFrame( NULL, sizeof( AstFrame ), !class_init, &class_vtab, - "Frame", naxes ); - -/* If successful, note that the virtual function table has been initialised. */ - if ( astOK ) { - class_init = 1; - -/* Obtain the variable argument list and pass it along with the options string - to the astVSet method to initialise the new Frame's attributes. */ - va_start( args, options ); - astVSet( new, options, NULL, args ); - va_end( args ); - -/* If an error occurred, clean up by deleting the new object. */ - if ( !astOK ) new = astDelete( new ); - } - -/* Return an ID value for the new Frame. */ - return astMakeId( new ); -} - -void astPermAxesId_( AstFrame *this, const int perm[], int *status ) { -/* -*++ -* Name: -c astPermAxes -f AST_PERMAXES - -* Purpose: -* Permute the axis order in a Frame. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c void astPermAxes( AstFrame *this, const int perm[] ) -f CALL AST_PERMAXES( THIS, PERM, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function permutes the order in which a Frame's axes occur. -f This routine permutes the order in which a Frame's axes occur. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c perm -f PERM( * ) = INTEGER (Given) -* An array with one element for each axis of the Frame (Naxes -* attribute). This should list the axes in their new order, -* using the original axis numbering (which starts at 1 for the -* first axis). -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -* - Only genuine permutations of the axis order are permitted, so -c each axis must be referenced exactly once in the "perm" array. -f each axis must be referenced exactly once in the PERM array. -* - If successive axis permutations are applied to a Frame, then -* the effects are cumulative. -*-- - -* Implementation Notes: -* This function implements the public interface for the -* astPermAxes method. It is identical to astPermAxes_ except that -* the axis numbers in the "perm" array are decremented by 1 before -* use. This is to allow the public interface to use one-based axis -* numbering (internally, zero-based axis numbering is used). -*/ - -/* Local Variables: */ - int *perm1; /* Pointer to modified perm array */ - int axis; /* Loop counter for Frame axes */ - int naxes; /* Number of Frame axes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain the number of Frame axes. */ - naxes = astGetNaxes( this ); - -/* Allocate an array to hold a modified version of the "perm" - array. */ - perm1 = astMalloc( sizeof( int ) * (size_t) naxes ); - if ( astOK ) { - -/* Make a modified copy of the "perm" array by subtracting one from - each element. This allows the public interface to use one-based - axis numbering, whereas all internal code is zero-based. */ - for ( axis = 0; axis < naxes; axis++ ) perm1[ axis ] = perm[ axis ] - 1; - -/* Invoke the normal astPermAxes_ function to permute the Frame's axes. */ - astPermAxes( this, perm1 ); - } - -/* Free the temporary array. */ - perm1 = astFree( perm1 ); -} - -AstFrame *astPickAxesId_( AstFrame *this, int naxes, const int axes[], - AstMapping **map, int *status ) { -/* -*++ -* Name: -c astPickAxes -f AST_PICKAXES - -* Purpose: -* Create a new Frame by picking axes from an existing one. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c AstFrame *astPickAxes( AstFrame *this, int naxes, const int axes[], -c AstMapping **map ) -f RESULT = AST_PICKAXES( THIS, NAXES, AXES, MAP, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -* This function creates a new Frame whose axes are copied from an -* existing Frame along with other Frame attributes, such as its -* Title. Any number (zero or more) of the original Frame's axes -* may be copied, in any order, and additional axes with default -* attributes may also be included in the new Frame. -* -c Optionally, a Mapping that converts between the coordinate -f A Mapping that converts between the coordinate -* systems described by the two Frames will also be returned. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the original Frame. -c naxes -f NAXES = INTEGER (Given) -* The number of axes required in the new Frame. -c axes -f AXES( NAXES ) = INTEGER (Given) -c An array, with "naxes" elements, which lists the axes to be -f An array which lists the axes to be -* copied. These should be given in the order required in the -* new Frame, using the axis numbering in the original Frame -* (which starts at 1 for the first axis). Axes may be selected -* in any order, but each may only be used once. If additional -* (default) axes are also to be included, the corresponding -* elements of this array should be set to zero. -c map -f MAP = INTEGER (Returned) -c Address of a location in which to return a pointer to a new -f 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 original and new Frames. The Mapping's -* forward transformation will convert coordinates from the -* original Frame into the new one, and vice versa. -c -c If this Mapping is not required, a NULL value may be supplied -c for this parameter. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astPickAxes() -f AST_PICKAXES = INTEGER -* A pointer to the new Frame. - -* Applicability: -* Frame -* This function applies to all Frames. The class of Frame returned -* may differ from that of the original Frame, depending on which -* axes are selected. For example, if a single axis is picked from a -* SkyFrame (which must always have two axes) then the resulting -* Frame cannot be a valid SkyFrame, so will revert to the parent -* class (Frame) instead. -* FrameSet -* Using this function on a FrameSet is identical to using it on -* the current Frame in the FrameSet. The returned Frame will not -* be a FrameSet. -* Region -* If this function is used on a Region, an attempt is made to -* retain the bounds information on the selected axes. If -* succesful, the returned Frame will be a Region of some class. -* Otherwise, the returned Frame is obtained by calling this -* function on the Frame represented by the supplied Region (the -* returned Frame will then not be a Region). In order to be -* succesful, the selected axes in the Region must be independent -* of the others. For instance, a Box can be split in this way but -* a Circle cannot. Another requirement for success is that no -* default axes are added (that is, the -c "axes" -f AXES -* array must not contain any zero values. - -* Notes: -c - The new Frame will contain a "deep" copy (c.f. astCopy) of all -f - The new Frame will contain a "deep" copy (c.f. AST_COPY) of all -* the data selected from the original Frame. Modifying any aspect -* of the new Frame will therefore not affect the original one. -* - 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: -* This function implements the public interface for the -* astPickAxes method. It is identical to astPickAxes_ except for -* the following: -* -* - The axis numbers in the "axes" array are decremented by 1 before -* use. This is to allow the public interface to use one-based axis -* numbering (internally, zero-based axis numbering is used). -* -* - An ID value is returned via the "map" parameter (if used) -* instead of a true C pointer. This is required because this -* conversion cannot be performed by the macro that invokes the -* function. -*/ - -/* Local Variables: */ - AstFrame *result; /* Pointer to result Frame */ - int *axes1; /* Pointer to modified axes array */ - int axis; /* Loop counter for axes */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Allocate an array to hold a modified version of the "axes" array - (check that "naxes" is valid first - if not, this error will be - reported by astPickAxes_ below). */ - axes1 = ( naxes >= 0 ) ? astMalloc( sizeof( int ) * (size_t) naxes ) : - NULL; - if ( astOK ) { - -/* Make a modified copy of the "axes" array by subtracting one from - each element. This allows the public interface to use one-based - axis numbering, whereas all internal code is zero-based. */ - for ( axis = 0; axis < naxes; axis++ ) axes1[ axis ] = axes[ axis ] - 1; - -/* Invoke the normal astPickAxes_ function to select the required axes. */ - result = astPickAxes( this, naxes, axes1, map ); - } - -/* Free the temporary array. */ - axes1 = astFree( axes1 ); - -/* If required, return an ID value for the Mapping. */ - if ( map ) *map = astMakeId( *map ); - -/* Return the result. */ - return result; -} - -int astUnformatId_( AstFrame *this, int axis, const char *string, - double *value, int *status ) { -/* -*++ -* Name: -c astUnformat -f AST_UNFORMAT - -* Purpose: -* Read a formatted coordinate value for a Frame axis. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frame.h" -c int astUnformat( AstFrame *this, int axis, const char *string, -c double *value ) -f RESULT = AST_UNFORMAT( THIS, AXIS, STRING, VALUE, STATUS ) - -* Class Membership: -* Frame method. - -* Description: -c This function reads a formatted coordinate value (given as a -c character string) for a Frame axis and returns the equivalent -c numerical (double) value. It also returns the number of -c characters read from the string. -f This function reads a formatted coordinate value (given as a -f character string) for a Frame axis and returns the equivalent -f numerical (double precision) value. It also returns the number -f of characters read from the string. -* -c The principle use of this function is in decoding user-supplied -c input which contains formatted coordinate values. Free-format -c input is supported as far as possible. If input is ambiguous, it -c is interpreted with reference to the Frame's attributes (in -c particular, the Format string associated with the Frame's -c axis). This function is, in essence, the inverse of astFormat. -f The principle use of this function is in decoding user-supplied -f input which contains formatted coordinate values. Free-format -f input is supported as far as possible. If input is ambiguous, it -f is interpreted with reference to the Frame's attributes (in -f particular, the Format string associated with the Frame's -f axis). This function is, in essence, the inverse of AST_FORMAT. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the Frame. -c axis -f AXIS = INTEGER (Given) -* The number of the Frame axis for which a coordinate value is to -* be read (axis numbering starts at 1 for the first axis). -c string -f STRING = CHARACTER * ( * ) (Given) -c Pointer to a null-terminated character string containing the -c formatted coordinate value. -f A character string containing the formatted coordinate value. -* This string may contain additional information following the -* value to be read, in which case reading stops at the first -* character which cannot be interpreted as part of the value. -* Any white space before or after the value is discarded. -c value -f VALUE = DOUBLE PRECISION (Returned) -c Pointer to a double in which the coordinate value read will be -c returned. -f The coordinate value read. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astUnformat() -f AST_UNFORMAT = INTEGER -* The number of characters read from the string in order to -* obtain the coordinate value. This will include any white -* space which occurs before or after the value. - -* Applicability: -* Frame -* This function applies to all Frames. See the "Frame Input -* Format" section below for details of the input formats -* accepted by a basic Frame. -* SkyFrame -* The SkyFrame class re-defines the input format to be suitable -* for representing angles and times, with the resulting -* coordinate value returned in radians. See the "SkyFrame -* Input Format" section below for details of the formats -* accepted. -* FrameSet -* The input formats accepted by a FrameSet are determined by -* its current Frame (as specified by the Current attribute). - -* Frame Input Format -* The input format accepted for a basic Frame axis is as follows: -* - An optional sign, followed by: -* - A sequence of one or more digits possibly containing a decimal point, -* followed by: -* - An optional exponent field. -* - The exponent field, if present, consists of "E" or "e" -* followed by a possibly signed integer. -* -* Examples of acceptable Frame input formats include: -* - 99 -* - 1.25 -* - -1.6 -* - 1E8 -* - -.99e-17 -* - <bad> - -* SkyFrame Input Format -* The input format accepted for a SkyFrame axis is as follows: -* - An optional sign, followed by between one and three fields -* representing either degrees, arc-minutes, arc-seconds or hours, -* minutes, seconds (e.g. "-12 42 03"). -* - Each field should consist of a sequence of one or more digits, -* which may include leading zeros. At most one field may contain a -* decimal point, in which case it is taken to be the final field -* (e.g. decimal degrees might be given as "124.707", while degrees -* and decimal arc-minutes might be given as "-13 33.8"). -* - The first field given may take any value, allowing angles and -* times outside the conventional ranges to be -* represented. However, subsequent fields must have values of less -* than 60 (e.g. "720 45 31" is valid, whereas "11 45 61" is not). -* - Fields may be separated by white space or by ":" (colon), but -* the choice of separator must be used consistently throughout the -* value. Additional white space may be present around fields and -* separators (e.g. "- 2: 04 : 7.1"). -* - The following field identification characters may be used as -* separators to replace either of those above (or may be appended -* to the final field), in order to identify the field to which -* they are appended: "d"---degrees; "h"---hours; "m"---minutes of -* arc or time; "s"---seconds of arc or time; "'" (single -* quote)---minutes of arc; """ (double quote)---seconds of arc. -* Either lower or upper case may be used. Fields must be given in -* order of decreasing significance (e.g. "-11D 3' 14.4"" or -* "22h14m11.2s"). -* - The presence of any of the field identification characters -* "d", "'" (single quote) or """ (double quote) indicates that the -* value is to be interpreted as an angle. Conversely, the presence -* of "h" indicates that it is to be interpreted as a time (with 24 -* hours corresponding to 360 degrees). Incompatible angle/time -* identification characters may not be mixed (e.g. "10h14'3"" is -* not valid). The remaining field identification characters and -* separators do not specify a preference for an angle or a time -* and may be used with either. -c - If no preference for an angle or a time is expressed anywhere -c within the value, it is interpreted as an angle if the Format -c attribute string associated with the SkyFrame axis generates an -c angle and as a time otherwise. This ensures that values produced -c by astFormat are correctly interpreted by astUnformat. -f - If no preference for an angle or a time is expressed anywhere -f within the value, it is interpreted as an angle if the Format -f attribute string associated with the SkyFrame axis generates an -f angle and as a time otherwise. This ensures that values produced -f by AST_FORMAT are correctly interpreted by AST_UNFORMAT. -* - Fields may be omitted, in which case they default to zero. The -* remaining fields may be identified by using appropriate field -* identification characters (see above) and/or by adding extra -* colon separators (e.g. "-05m13s" is equivalent to "-:05:13"). If -* a field is not identified explicitly, it is assumed that -* adjacent fields have been given, after taking account of any -* extra separator characters (e.g. "14:25.4s" specifies minutes -* and seconds, while "14::25.4s" specifies degrees and seconds). -c - If fields are omitted in such a way that the remaining ones -c cannot be identified uniquely (e.g. "01:02"), then the first -c field (either given explicitly or implied by an extra leading -c colon separator) is taken to be the most significant field that -c astFormat would produce when formatting a value (using the -c Format attribute associated with the SkyFrame axis). By -c default, this means that the first field will normally be -c interpreted as degrees or hours. However, if this does not -c result in consistent field identification, then the last field -c (either given explicitly or implied by an extra trailing colon -c separator) is taken to to be the least significant field that -c astFormat would produce. -f - If fields are omitted in such a way that the remaining ones -f cannot be identified uniquely (e.g. "01:02"), then the first -f field (either given explicitly or implied by an extra leading -f colon separator) is taken to be the most significant field that -f AST_FORMAT would produce when formatting a value (using the -f Format attribute associated with the SkyFrame axis). By -f default, this means that the first field will normally be -f interpreted as degrees or hours. However, if this does not -f result in consistent field identification, then the last field -f (either given explicitly or implied by an extra trailing colon -f separator) is taken to to be the least significant field that -f AST_FORMAT would produce. -* -c This final convention is intended to ensure that values formatted -c by astFormat which contain less than three fields will be -c correctly interpreted if read back using astUnformat, even if -c they do not contain field identification characters. -f This final convention is intended to ensure that values formatted -f by AST_FORMAT which contain less than three fields will be -f correctly interpreted if read back using AST_UNFORMAT, even if -f they do not contain field identification characters. -* -* Examples of acceptable SkyFrame input formats (with -* interpretation in parentheses) include: -* - -14d 13m 22.2s (-14d 13' 22.2") -* - + 12:34:56.7 (12d 34' 56.7" or 12h 34m 56.7s) -* - 001 : 02 : 03.4 (1d 02' 03.4" or 1h 02m 03.4s) -* - 22h 30 (22h 30m 00s) -* - 136::10" (136d 00' 10" or 136h 00m 10s) -* - -14M 27S (-0d 14' 27" or -0h 14m 27s) -* - -:14: (-0d 14' 00" or -0h 14m 00s) -* - -::4.1 (-0d 00' 04.1" or -0h 00m 04.1s) -* - .9" (0d 00' 00.9") -* - d12m (0d 12' 00") -* - H 12:22.3s (0h 12m 22.3s) -* - <bad> (AST__BAD) -* -* Where alternative interpretations are shown, the choice of angle or -* time depends on the associated Format(axis) attribute. - -* Notes: -* - 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. -c - Beware that it is possible for a formatting error part-way -c through an input string to terminate input before it has been -c completely read, but to yield a coordinate value that appears -c valid. For example, if a user types "1.5r6" instead of "1.5e6", -c the "r" will terminate input, giving an incorrect coordinate -c value of 1.5. It is therefore most important to check the return -c value of this function to ensure that the correct number of -c characters have been read. -f - Beware that it is possible for a formatting error part-way -f through an input string to terminate input before it has been -f completely read, but to yield a coordinate value that appears -f valid. For example, if a user types "1.5R6" instead of "1.5E6", -f the "R" will terminate input, giving an incorrect coordinate -f value of 1.5. It is therefore most important to check the return -f value of this function to ensure that the correct number of -f characters have been read. -* - An error will result if a value is read which appears to have -* the correct format, but which cannot be converted into a valid -* coordinate value (for instance, because the value of one or more -* of its fields is invalid). -* - The string "<bad>" is recognised as a special case and will -* yield the coordinate value AST__BAD without error. The test for -* this string is case-insensitive and also permits embedded white -* space. -c - A function result of zero will be returned and no coordinate -c value will be returned via the "value" pointer if this function -c is invoked with the AST error status set, or if it should fail -c for any reason. -f - A function result of zero will be returned and no coordinate -f value will be returned via the VALUE argument if this function -f is invoked with the AST error status set, or if it should fail -f for any reason. -*-- - -* Implementation Notes: -* This function implements the public interface for the -* astUnformat method. It is identical to astUnformat_ except that: -* -* - The axis index is decremented by 1 before use. This allows the -* public interface to use 1-based axis numbers (whereas internally -* axis numbers are zero-based). -*/ - -/* Invoke the normal astUnformat_ function, adjusting the axis index - to become zero-based. */ - return astUnformat( this, axis - 1, string, value ); -} - - - - - - - - - - - - - |