diff options
author | William Joye <wjoye@cfa.harvard.edu> | 2019-05-10 18:41:55 (GMT) |
---|---|---|
committer | William Joye <wjoye@cfa.harvard.edu> | 2019-05-10 18:41:55 (GMT) |
commit | 75fab9d80911f74aaab738fa9ab8a4f9b0f57a6b (patch) | |
tree | 8d0d428ac62291f834ea8927bfa82c115ff1689d /ast/frameset.c | |
parent | 0609bafa2688ce94fbfdc1ea496b20c3fac732f1 (diff) | |
download | blt-75fab9d80911f74aaab738fa9ab8a4f9b0f57a6b.zip blt-75fab9d80911f74aaab738fa9ab8a4f9b0f57a6b.tar.gz blt-75fab9d80911f74aaab738fa9ab8a4f9b0f57a6b.tar.bz2 |
upgrade ast 8.7.1
Diffstat (limited to 'ast/frameset.c')
-rw-r--r-- | ast/frameset.c | 13337 |
1 files changed, 0 insertions, 13337 deletions
diff --git a/ast/frameset.c b/ast/frameset.c deleted file mode 100644 index 8795790..0000000 --- a/ast/frameset.c +++ /dev/null @@ -1,13337 +0,0 @@ -/* -*class++ -* Name: -* FrameSet - -* Purpose: -* Set of inter-related coordinate systems. - -* Constructor Function: -c astFrameSet -f AST_FRAMESET - -* Description: -* A FrameSet consists of a set of one or more Frames (which -* describe coordinate systems), connected together by Mappings -* (which describe how the coordinate systems are inter-related). A -* FrameSet makes it possible to obtain a Mapping between any pair -* of these Frames (i.e. to convert between any of the coordinate -* systems which it describes). The individual Frames are -* identified within the FrameSet by an integer index, with Frames -* being numbered consecutively from one as they are added to the -* FrameSet. -* -* Every FrameSet has a "base" Frame and a "current" Frame (which -* are allowed to be the same). Any of the Frames may be nominated -* to hold these positions, and the choice is determined by the -* values of the FrameSet's Base and Current attributes, which hold -* the indices of the relevant Frames. By default, the first Frame -* added to a FrameSet is its base Frame, and the last one added is -* its current Frame. -* -* The base Frame describes the "native" coordinate system of -* whatever the FrameSet is used to calibrate (e.g. the pixel -* coordinates of an image) and the current Frame describes the -* "apparent" coordinate system in which it should be viewed -* (e.g. displayed, etc.). Any further Frames represent a library -* of alternative coordinate systems, which may be selected by -* making them current. -* -* When a FrameSet is used in a context that requires a Frame, -* (e.g. obtaining its Title value, or number of axes), the current -* Frame is used. A FrameSet may therefore be used in place of its -* current Frame in most situations. -* -* When a FrameSet is used in a context that requires a Mapping, -* the Mapping used is the one between its base Frame and its -* current Frame. Thus, a FrameSet may be used to convert "native" -* coordinates into "apparent" ones, and vice versa. Like any -c Mapping, a FrameSet may also be inverted (see astInvert), which -f Mapping, a FrameSet may also be inverted (see AST_INVERT), which -* has the effect of interchanging its base and current Frames and -* hence of reversing the Mapping between them. -* -* Regions may be added into a FrameSet (since a Region is a type of -* Frame), either explicitly or as components within CmpFrames. In -* this case the Mapping between a pair of Frames within a FrameSet -* will include the masking effects produced by any Regions included -* in the path between the Frames. - -* Inheritance: -* The FrameSet class inherits from the Frame class. - -* Attributes: -* In addition to those attributes common to all Frames, every -* FrameSet also has the following attributes: -* -* - AllVariants: List of all variant mappings stored with current Frame -* - Base: FrameSet base Frame index -* - Current: FrameSet current Frame index -* - Nframe: Number of Frames in a FrameSet -* - Variant: Name of variant mapping in use by current Frame - -* Every FrameSet also inherits any further attributes that belong -* to its current Frame, regardless of that Frame's class. (For -* example, the Equinox attribute, defined by the SkyFrame class, is -* inherited by any FrameSet which has a SkyFrame as its current -* Frame.) The set of attributes belonging to a FrameSet may therefore -* change when a new current Frame is selected. - -* Functions: -c In addition to those functions applicable to all Frames, the -c following functions may also be applied to all FrameSets: -f In addition to those routines applicable to all Frames, the -f following routines may also be applied to all FrameSets: -* -c - astAddFrame: Add a Frame to a FrameSet to define a new coordinate -c system -c - astAddVariant: Add a variant Mapping to the current Frame -c - astGetFrame: Obtain a pointer to a specified Frame in a FrameSet -c - astGetMapping: Obtain a Mapping between two Frames in a FrameSet -c - astMirrorVariants: Make the current Frame mirror variant Mappings in another Frame -c - astRemapFrame: Modify a Frame's relationship to the other Frames in a -c FrameSet -c - astRemoveFrame: Remove a Frame from a FrameSet -f - AST_ADDFRAME: Add a Frame to a FrameSet to define a new coordinate -f system -f - AST_ADDVARIANT: Add a variant Mapping to the current Frame -f - AST_GETFRAME: Obtain a pointer to a specified Frame in a FrameSet -f - AST_GETMAPPING: Obtain a Mapping between two Frames in a FrameSet -f - AST_MIRRORVARIANTS: Make the current Frame mirror variant Mappings in another Frame -f - AST_REMAPFRAME: Modify a Frame's relationship to the other Frames in a -f FrameSet -f - AST_REMOVEFRAME: Remove a Frame from a FrameSet - -* 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) - -* History: -* 16-FEB-1996 (RFWS): -* Original version. -* 5-JUN-1996 (RFWS): -* Tidied up, etc. -* 2-JUL-1996 (RFWS): -* Fixed bug in astRemoveFrame which caused the base/current -* Frame index to be wrong. -* 12-JUL-1996 (RFWS): -* Over-ride the astReportPoints method to provide -* Frame-specific formatting. -* 12-AUG-1996 (RFWS): -* Upgraded to provide a public interface, plus improvements to -* astAlign and the handling of nodes as Frames are -* added/removed. -* 11-SEP-1996 (RFWS): -* Added Gap. -* 25-SEP-1996 (RFWS): -* Added I/O facilities. -* 30-MAY-1997 (RFWS): -* Add special treatment for the ID attribute (which is not -* derived from the current Frame). -* 10-JUN-1997 (RFWS): -* Rationalised the astConvert implementation. -* 11-JUN-1997 (RFWS): -* Added the FindFrame implementation. -* 27-JUN-1997 (RFWS): -* Fixed bug which caused certain Mapping attributes to be -* handled by the current Frame instead of by the member -* functions defined by this class. -* 3-JUL-1997 (RFWS): -* Fixed bug: failing to extend the invert array in -* astRemapFrame. -* 10-JUL-1997 (RFWS): -* Over-ride the astSimplify method. -* 14-NOV-1997 (RFWS): -* Fixed error in loop implementing search over domains in -* FindFrame. -* 20-NOV-1997 (RFWS): -* Fixed bug in default Base and Current attribute values when a -* FrameSet has been inverted. -* 20-NOV-1997 (RFWS): -* Modified astConvert to use the current Frame of the "to" -* FrameSet as the destination coordinate system (instead of the -* base Frame) and to modify its Base attribute instead of its -* Current attribute. -* 22-DEC-1997 (RFWS): -* Further modified astConvert to convert from the Current Frame -* of the "from" FrameSet and to modify its Base -* attribute. Frame search order also reversed if the Invert -* attribute is non-zero for either FrameSet. -* 19-JAN-1998 (RFWS): -* Installed the TidyNodes function. -* 20-JAN-1998 (RFWS): -* Implemented preservation of FrameSet integrity when attribute -* values associated with the current Frame are modified. -* 24-FEB-1998 (RFWS): -* Added the ForceCopy function to allow integrity to be preserved -* when there are multiple references to the same Frame. -* 25-FEB-1998 (RFWS): -* Over-ride the astUnformat method. -* 24-MAR-1998 (RFWS): -* Fixed unterminated comment causing problems in CombineMaps. -* 6-APR-1998 (RFWS): -* Fixed another unterminated comment in CombineMaps. -* 27-MAY-1998 (RFWS): -* Fixed bug: failure to record new invert flag value after -* simplifying a CmpMap in TidyNodes. -* 17-DEC-2002 (DSB): -* Override accessors for Frame attributes Top, Bottom, Epoch, -* System, AlignSystem and ActiveUnit. -* 8-JAN-2003 (DSB): -* Changed private InitVtab method to protected astInitFrameSetVtab -* method. -* 24-JAN-2004 (DSB): -* o Override the astFields method. -* o Add argument "fmt" to Abbrev. -* 23-MAR-2004 (DSB): -* Modified astGetMapping and Span to include the clipping effect of -* any Regions in the path between the two supplied Frames. -* 24-AUG-2004 (DSB): -* - Override various methods inherited from Frame (astAngle, -* astAxAngle, astAxDistance, astAxOffset, astCheckPerm, astOffset2, -* astResolve, astSystemCode, astSystemString, astValidateSystem, -* astValidateAxisSelection). These should have been overridden a -* long time ago! -* 8-SEP-2004 (DSB): -* Override astResolvePoints. -* 12-MAY-2005 (DSB): -* Override astNormBox method. -* 12-AUG-2005 (DSB): -* Override ObsLat and ObsLon accessor methods. -* 14-FEB-2006 (DSB): -* Override astGetObjSize. -* 15-MAY-2006 (DSB): -* Override astEqual. -* 30-JUN-2006 (DSB): -* Allow astAbbrev to have a null "str1" value. -* 22-JUN-2007 (DSB): -* Modify VSet to avoid using the args va_list twice since the -* first use (by the parent VSet function) invalidates the va_list -* causing a segvio to be generated by the second use (when -* formatting an error message). -* 11-JAN-2008 (DSB): -* Override the astRate method. -* 17-NOV-2008 (DSB): -* Correct parent class in invocation of astMAKE_ISA. -* 14-JAN-2009 (DSB): -* Override the astIntersect method. -* 18-JUN-2009 (DSB): -* Override ObsAlt accessor methods. -* 30-OCT-2009 (DSB): -* Make the Ident attribute relate to the FrameSet, not the current -* Frame. -* 22-MAR-2011 (DSB): -* Override astFrameGrid method. -* 29-APR-2011 (DSB): -* Prevent astFindFrame from matching a subclass template against a -* superclass target. -* 2-SEP-2011 (DSB): -* Fix FrameSet implememntation of astEqual (mapping comparison -* tests were logically inverted). -* 3-OCT-2012 (DSB): -* Fix bug in AppendAxes that could cause internal Mappings to -* be inverted unintentionally when astAddFrame is called with -* iframe=AST__ALLFRAMES. -* 29-APR-2013 (DSB): -* Added attributes AllVariants and Variant. Also added methods -* astAddVariant and astMirrorVariants. -* 25-SEP-2014 (DSB): -* Allow Base and Current attributes to be specified by giving a -* Domain name. -* 17-APR-2015 (DSB): -* Added Centre. -* 28-APR-2015 (DSB): -* astAdFrame now takes deep copies of the supplied mapping and -* frame, rather than just cloning their pointers. So the modified -* FrameSet is now independent of the supplied Mapping and Frame -* objects. -* 26-OCT-2016 (DSB): -* Override the AxNorm method. -* 07-APR-2017 (GSB): -* Override Dtai and Dut1 accessor methods. -* 07-NOV-2017 (GSB): -* In AddFrame, check to see if a FrameSet is supplied in place of -* a Mapping and if so, use the FrameSet's base -> current Mapping -* instead. -* 11-DEC-2017 (DSB): -* Added method astGetNode. -*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 FrameSet - -#define GETALLVARIANTS_BUFF_LEN 200 - -/* -* Name: -* MAKE_CLEAR - -* Purpose: -* Define a function to clear an attribute value for a FrameSet. - -* Type: -* Private macro. - -* Synopsis: -* #include "frameset.h" -* MAKE_CLEAR(attribute) - -* Class Membership: -* Defined by the FrameSet class. - -* Description: -* This macro expands to an implementation of a private member function -* of the form: -* -* static void Clear<Attribute>( AstFrame *this ) -* -* that clears the value of a specified attribute for the current Frame -* of a FrameSet (this). This function is intended to over-ride the -* astClear<Attribute> method inherited from the Frame class. - -* Parameters: -* attribute -* Name of the attribute, as it appears in the function name. -*/ - -/* Define the macro. */ -#define MAKE_CLEAR(attribute) \ -static void Clear##attribute( AstFrame *this_frame, int *status ) { \ -\ -/* Local Variables: */ \ - AstFrame *fr; /* Pointer to current Frame */ \ - AstFrameSet *this; /* Pointer to the FrameSet structure */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return; \ -\ -/* Obtain a pointer to the FrameSet structure. */ \ - this = (AstFrameSet *) this_frame; \ -\ -/* Obtain a pointer to the current Frame and invoke its astClear<Attribute> \ - method. Annul the Frame pointer afterwards. */ \ - fr = astGetFrame( this, AST__CURRENT ); \ - astClear##attribute( fr ); \ - fr = astAnnul( fr ); \ -} - -/* -* Name: -* MAKE_CLEAR_AXIS - -* Purpose: -* Define a function to clear an attribute value for a FrameSet axis. - -* Type: -* Private macro. - -* Synopsis: -* #include "frameset.h" -* MAKE_CLEAR_AXIS(attribute) - -* Class Membership: -* Defined by the FrameSet class. - -* Description: -* This macro expands to an implementation of a private member function -* of the form: -* -* static void Clear<Attribute>( AstFrame *this, int axis ) -* -* that clears the value of a specified attribute for an axis of -* the current Frame of a FrameSet (this). This function is -* intended to over-ride the astClear<Attribute> method inherited -* from the Frame class. - -* Parameters: -* attribute -* Name of the attribute, as it appears in the function name. -*/ - -/* Define the macro. */ -#define MAKE_CLEAR_AXIS(attribute) \ -static void Clear##attribute( AstFrame *this_frame, int axis, int *status ) { \ -\ -/* Local Variables: */ \ - AstFrame *fr; /* Pointer to current Frame */ \ - AstFrameSet *this; /* Pointer to the FrameSet structure */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return; \ -\ -/* Obtain a pointer to the FrameSet structure. */ \ - this = (AstFrameSet *) this_frame; \ -\ -/* Validate the axis index supplied. */ \ - (void) astValidateAxis( this, axis, 1, "astClear" #attribute ); \ -\ -/* Obtain a pointer to the FrameSet's current Frame and invoke its \ - astClear<Attribute> method. Annul the Frame pointer afterwards. */ \ - fr = astGetFrame( this, AST__CURRENT ); \ - astClear##attribute( fr, axis ); \ - fr = astAnnul( fr ); \ -} - -/* -* Name: -* MAKE_GET - -* Purpose: -* Define a function to get an attribute value for a FrameSet. - -* Type: -* Private macro. - -* Synopsis: -* #include "frameset.h" -* MAKE_GET(attribute,type) - -* Class Membership: -* Defined by the FrameSet class. - -* Description: -* This macro expands to an implementation of a private member function -* of the form: -* -* static <type> Get<Attribute>( AstFrame *this ) -* -* that gets the value of a specified attribute for the current Frame -* of a FrameSet (this). This function is intended to over-ride the -* astGet<Attribute> method inherited from the Frame class. - -* Parameters: -* attribute -* Name of the attribute, as it appears in the function name. -* type -* The C type of the attribute. -*/ - -/* Define the macro. */ -#define MAKE_GET(attribute,type) \ -static type Get##attribute( AstFrame *this_frame, int *status ) { \ -\ -/* Local Variables: */ \ - AstFrame *fr; /* Pointer to current Frame */ \ - AstFrameSet *this; /* Pointer to the FrameSet structure */ \ - type result; /* Value to return */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return (type) 0; \ -\ -/* Obtain a pointer to the FrameSet structure. */ \ - this = (AstFrameSet *) this_frame; \ -\ -/* Obtain a pointer to the current Frame and invoke its \ - astGet<Attribute> method. Annul the Frame pointer afterwards. */ \ - fr = astGetFrame( this, AST__CURRENT ); \ - result = astGet##attribute( fr ); \ - fr = astAnnul( fr ); \ -\ -/* If an error occurred, clear the result value. */ \ - if ( !astOK ) result = (type) 0; \ -\ -/* Return the result. */ \ - return result; \ -} - -/* -* Name: -* MAKE_GET_AXIS - -* Purpose: -* Define a function to get an attribute value for a FrameSet axis. - -* Type: -* Private macro. - -* Synopsis: -* #include "frameset.h" -* MAKE_GET_AXIS(attribute,type) - -* Class Membership: -* Defined by the FrameSet class. - -* Description: -* This macro expands to an implementation of a private member function -* of the form: -* -* static <type> Get<Attribute>( AstFrame *this, int axis ) -* -* that gets the value of a specified attribute for an axis of the -* current Frame of a FrameSet (this). This function is intended to -* over-ride the astGet<Attribute> method inherited from the Frame -* class. - -* Parameters: -* attribute -* Name of the attribute, as it appears in the function name. -* type -* The C type of the attribute. -*/ - -/* Define the macro. */ -#define MAKE_GET_AXIS(attribute,type) \ -static type Get##attribute( AstFrame *this_frame, int axis, int *status ) { \ -\ -/* Local Variables: */ \ - AstFrame *fr; /* Pointer to current Frame */ \ - AstFrameSet *this; /* Pointer to the FrameSet structure */ \ - type result; /* Value to return */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return (type) 0; \ -\ -/* Obtain a pointer to the FrameSet structure. */ \ - this = (AstFrameSet *) this_frame; \ -\ -/* Validate the axis index supplied. */ \ - (void) astValidateAxis( this, axis, 1, "astGet" #attribute ); \ -\ -/* Obtain a pointer to the FrameSet's current Frame and invoke its \ - astGet<Attribute> method. Annul the Frame pointer afterwards. */ \ - fr = astGetFrame( this, AST__CURRENT ); \ - result = astGet##attribute( fr, axis ); \ - fr = astAnnul( fr ); \ -\ -/* If an error occurred, clear the result value. */ \ - if ( !astOK ) result = (type) 0; \ -\ -/* Return the result. */ \ - return result; \ -} - -/* -* Name: -* MAKE_SET - -* Purpose: -* Define a function to set an attribute value for a FrameSet. - -* Type: -* Private macro. - -* Synopsis: -* #include "frameset.h" -* MAKE_SET(attribute,type) - -* Class Membership: -* Defined by the FrameSet class. - -* Description: -* This macro expands to an implementation of a private member function -* of the form: -* -* static void Set<Attribute>( AstFrame *this, <type> value ) -* -* that sets the value of a specified attribute for the current Frame -* of a FrameSet (this). This function is intended to over-ride the -* astSet<Attribute> method inherited from the Frame class. - -* Parameters: -* attribute -* Name of the attribute, as it appears in the function name. -* type -* The C type of the attribute. -*/ - -/* Define the macro. */ -#define MAKE_SET(attribute,type) \ -static void Set##attribute( AstFrame *this_frame, type value, int *status ) { \ -\ -/* Local Variables: */ \ - AstFrame *fr; /* Pointer to current Frame */ \ - AstFrameSet *this; /* Pointer to the FrameSet structure */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return; \ -\ -/* Obtain a pointer to the FrameSet structure. */ \ - this = (AstFrameSet *) this_frame; \ -\ -/* Obtain a pointer to the FrameSet's current Frame and invoke its \ - astSet<Attribute> method. Annul the Frame pointer afterwards. */ \ - fr = astGetFrame( this, AST__CURRENT ); \ - astSet##attribute( fr, value ); \ - fr = astAnnul( fr ); \ -} - -/* -* Name: -* MAKE_SET_AXIS - -* Purpose: -* Define a function to set an attribute value for a FrameSet axis. - -* Type: -* Private macro. - -* Synopsis: -* #include "frameset.h" -* MAKE_SET_AXIS(attribute,type) - -* Class Membership: -* Defined by the FrameSet class. - -* Description: -* This macro expands to an implementation of a private member function -* of the form: -* -* static void Set<Attribute>( AstFrame *this, int axis, <type> value ) -* -* that sets the value of a specified attribute for an axis of the -* current Frame of a FrameSet (this). This function is intended to -* over-ride the astSet<Attribute> method inherited from the Frame -* class. - -* Parameters: -* attribute -* Name of the attribute, as it appears in the function name. -* type -* The C type of the attribute. -*/ - -/* Define the macro. */ -#define MAKE_SET_AXIS(attribute,type) \ -static void Set##attribute( AstFrame *this_frame, int axis, type value, int *status ) { \ -\ -/* Local Variables: */ \ - AstFrame *fr; /* Pointer to current Frame */ \ - AstFrameSet *this; /* Pointer to the FrameSet structure */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return; \ -\ -/* Obtain a pointer to the FrameSet structure. */ \ - this = (AstFrameSet *) this_frame; \ -\ -/* Validate the axis index supplied. */ \ - (void) astValidateAxis( this, axis, 1, "astSet" #attribute ); \ -\ -/* Obtain a pointer to the FrameSet's current Frame and invoke its \ - astSet<Attribute> method. Annul the Frame pointer afterwards. */ \ - fr = astGetFrame( this, AST__CURRENT ); \ - astSet##attribute( fr, axis, value ); \ - fr = astAnnul( fr ); \ -} - -/* -* Name: -* MAKE_TEST - -* Purpose: -* Define a function to test if an attribute value is set for a FrameSet. - -* Type: -* Private macro. - -* Synopsis: -* #include "frameset.h" -* MAKE_TEST(attribute) - -* Class Membership: -* Defined by the FrameSet class. - -* Description: -* This macro expands to an implementation of a private member function -* of the form: -* -* static int Test<Attribute>( AstFrame *this ) -* -* that returns a boolean result (0 or 1) to indicate if the value -* of a specified attribute for the current Frame of a FrameSet -* (this) is set. This function is intended to over-ride the -* astTest<Attribute> method inherited from the Frame class. - -* Parameters: -* attribute -* Name of the attribute, as it appears in the function name. -*/ - -/* Define the macro. */ -#define MAKE_TEST(attribute) \ -static int Test##attribute( AstFrame *this_frame, int *status ) { \ -\ -/* Local Variables: */ \ - AstFrame *fr; /* Pointer to current Frame */ \ - AstFrameSet *this; /* Pointer to FrameSet structure */ \ - int result; /* Result to return */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return 0; \ -\ -/* Obtain a pointer to the FrameSet structure. */ \ - this = (AstFrameSet *) this_frame; \ -\ -/* Obtain a pointer to the FrameSet's current Frame and invoke its \ - astTest<Attribute> method. Annul the Frame pointer afterwards. */ \ - fr = astGetFrame( this, AST__CURRENT ); \ - result = astTest##attribute( fr ); \ - fr = astAnnul( fr ); \ -\ -/* If an error occurred, clear the result value. */ \ - if ( !astOK ) result = 0; \ -\ -/* Return the result. */ \ - return result; \ -} - -/* -* Name: -* MAKE_TEST_AXIS - -* Purpose: -* Define a function to test if an attribute value is set for a FrameSet -* axis. - -* Type: -* Private macro. - -* Synopsis: -* #include "frameset.h" -* MAKE_TEST_AXIS(attribute) - -* Class Membership: -* Defined by the FrameSet class. - -* Description: -* This macro expands to an implementation of a private member function -* of the form: -* -* static int Test<Attribute>( AstFrame *this, int axis ) -* -* that returns a boolean result (0 or 1) to indicate if the value -* of a specified attribute for an axis of the current Frame of a -* FrameSet (this) is set. This function is intended to over-ride -* the astTest<Attribute> method inherited from the Frame class. - -* Parameters: -* attribute -* Name of the attribute, as it appears in the function name. -*/ - -/* Define the macro. */ -#define MAKE_TEST_AXIS(attribute) \ -static int Test##attribute( AstFrame *this_frame, int axis, int *status ) { \ -\ -/* Local Variables: */ \ - AstFrame *fr; /* Pointer to current Frame */ \ - AstFrameSet *this; /* Pointer to the FrameSet structure */ \ - int result; /* Value to return */ \ -\ -/* Check the global error status. */ \ - if ( !astOK ) return 0; \ -\ -/* Obtain a pointer to the FrameSet structure. */ \ - this = (AstFrameSet *) this_frame; \ -\ -/* Validate the axis index supplied. */ \ - (void) astValidateAxis( this, axis, 1, "astTest" #attribute ); \ -\ -/* Obtain a pointer to the FrameSet's current Frame and invoke its \ - astTest<Attribute> method. Annul the Frame pointer afterwards. */ \ - fr = astGetFrame( this, AST__CURRENT ); \ - result = astTest##attribute( fr, axis ); \ - fr = astAnnul( fr ); \ -\ -/* If an error occurred, clear the result value. */ \ - if ( !astOK ) result = 0; \ -\ -/* Return the result. */ \ - return result; \ -} - -/* Header files. */ -/* ============= */ -/* Interface definitions. */ -/* ---------------------- */ - -#include "globals.h" /* Thread-safe global data access */ -#include "error.h" /* Error reporting facilities */ -#include "memory.h" /* Memory allocation facilities */ -#include "object.h" /* Base Object class */ -#include "mapping.h" /* Coordinate Mappings */ -#include "unitmap.h" /* Unit Mappings */ -#include "permmap.h" /* Coordinate permutation Mappings */ -#include "cmpmap.h" /* Compound Mappings */ -#include "frame.h" /* Parent Frame class */ -#include "frameset.h" /* Interface definition for this class */ -#include "cmpframe.h" /* Compound coordinate frames */ - -/* Error code definitions. */ -/* ----------------------- */ -#include "ast_err.h" /* AST error codes */ - -/* C header files. */ -/* --------------- */ -#include <ctype.h> -#include <limits.h> -#include <stdarg.h> -#include <stddef.h> -#include <stdio.h> -#include <string.h> - -/* Module Variables. */ -/* ================= */ - -/* Address of this static variable is used as a unique identifier for - member of this class. */ -static int class_check; - -/* Pointers to parent class methods which are extended by this class. */ -static int (* parent_getobjsize)( AstObject *, int * ); -static void (* parent_clear)( AstObject *, const char *, int * ); -static int (* parent_getusedefs)( AstObject *, int * ); -static void (* parent_vset)( AstObject *, const char *, char **, va_list, int * ); - -#if defined(THREAD_SAFE) -static int (* parent_managelock)( AstObject *, int, int, AstObject **, int * ); -#endif - -/* Define macros for accessing each item of thread specific global data. */ -#ifdef THREAD_SAFE - -/* Define how to initialise thread-specific globals. */ -#define GLOBAL_inits \ - globals->Class_Init = 0; \ - globals->GetAttrib_Buff[ 0 ] = 0; \ - globals->Integrity_Frame = NULL; \ - globals->Integrity_Method = ""; \ - globals->Integrity_Lost = 0; \ - globals->GetAllVariants_Buff[ 0 ] = 0; \ - -/* Create the function that initialises global data for this module. */ -astMAKE_INITGLOBALS(FrameSet) - -/* Define macros for accessing each item of thread specific global data. */ -#define class_init astGLOBAL(FrameSet,Class_Init) -#define class_vtab astGLOBAL(FrameSet,Class_Vtab) -#define getattrib_buff astGLOBAL(FrameSet,GetAttrib_Buff) -#define integrity_frame astGLOBAL(FrameSet,Integrity_Frame) -#define integrity_method astGLOBAL(FrameSet,Integrity_Method) -#define integrity_lost astGLOBAL(FrameSet,Integrity_Lost) -#define getallvariants_buff astGLOBAL(FrameSet,GetAllVariants_Buff) - - - -/* If thread safety is not needed, declare and initialise globals at static - variables. */ -#else - -/* Buffer returned by GetAttrib. */ -static char getattrib_buff[ AST__FRAMESET_GETATTRIB_BUFF_LEN + 1 ]; - -/* Variables associated with preserving FrameSet integrity. */ -static AstFrame *integrity_frame = NULL; /* Pointer to copy of current Frame */ -static const char *integrity_method = ""; /* Name of method being used */ -static int integrity_lost = 0; /* Current Frame modified? */ - - -/* Define the class virtual function table and its initialisation flag - as static variables. */ -static AstFrameSetVtab class_vtab; /* Virtual function table */ -static int class_init = 0; /* Virtual function table initialised? */ - -/* String buffers. */ -static char getallvariants_buff[ AST__FRAMESET_GETALLVARIANTS_BUFF_LEN + 1 ]; - -#endif - - -/* Prototypes for Private Member Functions. */ -/* ======================================== */ -static AstAxis *GetAxis( AstFrame *, int, int * ); -static AstFrame *GetFrame( AstFrameSet *, 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 AstLineDef *LineDef( AstFrame *, const double[2], const double[2], int * ); -static AstMapping *CombineMaps( AstMapping *, int, AstMapping *, int, int, int * ); -static AstMapping *GetMapping( AstFrameSet *, int, int, int * ); -static AstMapping *RemoveRegions( AstMapping *, int * ); -static AstMapping *Simplify( AstMapping *, int * ); -static AstObject *Cast( AstObject *, AstObject *, 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 AstSystemType SystemCode( AstFrame *, const char *, int * ); -static AstSystemType ValidateSystem( AstFrame *, AstSystemType, const char *, int * ); -static const char *Abbrev( AstFrame *, int, const char *, const char *, const char *, int * ); -static const char *Format( AstFrame *, int, double, int * ); -static const char *GetAttrib( AstObject *, const char *, int * ); -static const char *GetDomain( AstFrame *, int * ); -static const char *GetFormat( AstFrame *, int, int * ); -static const char *GetLabel( 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 char *GetAllVariants( AstFrameSet *, int * ); -static const char *SystemString( AstFrame *, AstSystemType, 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 double Rate( AstMapping *, double *, int, int, int * ); -static int *MapSplit( AstMapping *, int, const int *, AstMapping **, int * ); -static int Equal( AstObject *, AstObject *, int * ); -static int Fields( AstFrame *, int, const char *, const char *, int, char **, int *, double *, int * ); -static int ForceCopy( AstFrameSet *, int, int * ); -static int GetActiveUnit( AstFrame *, int * ); -static int GetBase( AstFrameSet *, int * ); -static int GetCurrent( AstFrameSet *, int * ); -static int GetDigits( AstFrame *, int * ); -static int GetDirection( AstFrame *, int, int * ); -static int GetIsLinear( AstMapping *, int * ); -static int GetMatchEnd( AstFrame *, int * ); -static int GetMaxAxes( AstFrame *, int * ); -static int GetMinAxes( AstFrame *, int * ); -static int GetNaxes( AstFrame *, int * ); -static int GetNframe( AstFrameSet *, int * ); -static int GetNin( AstMapping *, int * ); -static int GetNode( AstFrameSet *, int, int *, int *, AstMapping **, int *, int * ); -static int GetNout( AstMapping *, int * ); -static int GetObjSize( AstObject *, int * ); -static int GetPermute( AstFrame *, int * ); -static int GetPreserveAxes( AstFrame *, int * ); -static int GetTranForward( AstMapping *, int * ); -static int GetTranInverse( AstMapping *, int * ); -static int GetVarFrm( AstFrameSet *, int, int * ); -static int IsUnitFrame( AstFrame *, int * ); -static int LineContains( AstFrame *, AstLineDef *, int, double *, int * ); -static int LineCrossing( AstFrame *, AstLineDef *, AstLineDef *, double **, int * ); -static int Match( AstFrame *, AstFrame *, int, int **, int **, AstMapping **, AstFrame **, int * ); -static int Span( AstFrameSet *, AstFrame **, int, int, int, AstMapping **, int *, int * ); -static int SubFrame( AstFrame *, AstFrame *, int, const int *, const int *, AstMapping **, AstFrame **, int * ); -static int TestActiveUnit( AstFrame *, int * ); -static int TestAttrib( AstObject *, const char *, int * ); -static int TestBase( AstFrameSet *, int * ); -static int TestCurrent( AstFrameSet *, 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 Unformat( AstFrame *, int, const char *, double *, int * ); -static int ValidateAxis( AstFrame *, int, int, const char *, int * ); -static int ValidateFrameIndex( AstFrameSet *, int, const char *, int * ); -static void AddFrame( AstFrameSet *, int, AstMapping *, AstFrame *, int * ); -static void AppendAxes( AstFrameSet *, AstFrame *, int * ); -static void AxNorm( AstFrame *, int, int, int, double *, int * ); -static void CheckPerm( AstFrame *, const int *, const char *, int * ); -static void Clear( AstObject *, const char *, int * ); -static void ClearAttrib( AstObject *, const char *, int * ); -static void ClearBase( AstFrameSet *, int * ); -static void ClearCurrent( AstFrameSet *, 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 LineOffset( AstFrame *, AstLineDef *, double, double, double[2], int * ); -static void MatchAxes( AstFrame *, AstFrame *, int *, int * ); -static void MatchAxesX( AstFrame *, AstFrame *, int *, 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 RecordIntegrity( AstFrameSet *, int * ); -static void AddVariant( AstFrameSet *, AstMapping *, const char *, int * ); -static void MirrorVariants( AstFrameSet *, int, int * ); -static void RemapFrame( AstFrameSet *, int, AstMapping *, int * ); -static void RemoveFrame( AstFrameSet *, int, int * ); -static void RemoveMirrors( AstFrameSet *, 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 RestoreIntegrity( AstFrameSet *, int * ); -static void SetActiveUnit( AstFrame *, int, int * ); -static void SetAttrib( AstObject *, const char *, int * ); -static void SetAxis( AstFrame *, int, AstAxis *, int * ); -static void SetBase( AstFrameSet *, int, int * ); -static void SetCurrent( AstFrameSet *, int, 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 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 TidyNodes( AstFrameSet *, int * ); -static void VSet( AstObject *, const char *, char **, va_list, int * ); -static void ValidateAxisSelection( AstFrame *, int, const int *, const char *, int * ); - -static double GetBottom( AstFrame *, int, int * ); -static int TestBottom( AstFrame *, int, int * ); -static void ClearBottom( AstFrame *, int, int * ); -static void SetBottom( AstFrame *, int, double, int * ); - -static double GetTop( AstFrame *, int, int * ); -static int TestTop( AstFrame *, int, int * ); -static void ClearTop( AstFrame *, int, int * ); -static void SetTop( AstFrame *, int, double, int * ); - -static double GetEpoch( AstFrame *, int * ); -static int TestEpoch( AstFrame *, int * ); -static void ClearEpoch( AstFrame *, int * ); -static void SetEpoch( AstFrame *, double, int * ); - -static double 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 double GetObsAlt( AstFrame *, int * ); -static int TestObsAlt( AstFrame *, int * ); -static void ClearObsAlt( AstFrame *, int * ); -static void SetObsAlt( AstFrame *, double, int * ); - -static double GetObsLat( AstFrame *, int * ); -static int TestObsLat( AstFrame *, int * ); -static void ClearObsLat( AstFrame *, int * ); -static void SetObsLat( AstFrame *, double, int * ); - -static double GetObsLon( AstFrame *, int * ); -static int TestObsLon( AstFrame *, int * ); -static void ClearObsLon( AstFrame *, int * ); -static void SetObsLon( AstFrame *, double, int * ); - -static int GetUseDefs( AstObject *, int * ); - -static AstSystemType GetSystem( AstFrame *, int * ); -static int TestSystem( AstFrame *, int * ); -static void ClearSystem( AstFrame *, int * ); -static void SetSystem( AstFrame *, AstSystemType, int * ); - -static AstSystemType GetAlignSystem( AstFrame *, int * ); -static int TestAlignSystem( AstFrame *, int * ); -static void ClearAlignSystem( AstFrame *, int * ); -static void SetAlignSystem( AstFrame *, AstSystemType, int * ); - -static const char *GetVariant( AstFrameSet *, int * ); -static int TestVariant( AstFrameSet *, int * ); -static void ClearVariant( AstFrameSet *, int * ); -static void SetVariant( AstFrameSet *, const char *, int * ); - -#if defined(THREAD_SAFE) -static int ManageLock( AstObject *, int, int, AstObject **, int * ); -#endif - -/* Member functions. */ -/* ================= */ -static const char *Abbrev( AstFrame *this_frame, int axis, const char *fmt, - const char *str1, const char *str2, int *status ) { -/* -* Name: -* Abbrev - -* Purpose: -* Abbreviate a formatted FrameSet axis value by skipping leading fields. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* const char *Abbrev( AstFrame *this, int axis, const char *fmt, -* const char *str1, const char *str2, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astAbbrev -* method inherited from the Frame class). - -* Description: -* This function compares two FrameSet 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 FrameSet. -* axis -* The number of the FrameSet 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. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A pointer into the "str2" string which locates the first -* character in the first field that differs between the two -* formatted values. -* -* If the two values have no leading fields in common, the returned -* value will point at the start of string "str2". If the two -* values are equal, it will point at the terminating null at the -* end of this string. - -* Notes: -* - This function assumes that the format specification used was -* the same when both values were formatted and that they both -* apply to the same FrameSet axis. -* - A pointer to the start of "str2" will be returned if this -* function is invoked with the global error status set, or if it -* should fail for any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - const char *result; /* Pointer value to return */ - -/* Check the global error status. */ - if ( !astOK ) return str2; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis, 1, "astAbbrev" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astAbbrev method to perform the processing. Annul the Frame - pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astAbbrev( fr, axis, fmt, str1, str2 ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = str2; - -/* Return the result. */ - return result; -} - -static void AddFrame( AstFrameSet *this, int iframe, AstMapping *map0, - AstFrame *frame, int *status ) { -/* -*++ -* Name: -c astAddFrame -f AST_ADDFRAME - -* Purpose: -* Add a Frame to a FrameSet to define a new coordinate system. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frameset.h" -c void astAddFrame( AstFrameSet *this, int iframe, AstMapping *map, -c AstFrame *frame ) -f CALL AST_ADDFRAME( THIS, IFRAME, MAP, FRAME, STATUS ) - -* Class Membership: -* FrameSet method. - -* Description: -c This function adds a new Frame and an associated Mapping to a -f This routine adds a new Frame and an associated Mapping to a -* FrameSet so as to define a new coordinate system, derived from -* one which already exists within the FrameSet. The new Frame then -* becomes the FrameSet's current Frame. -* -c This function -f This routine -* may also be used to merge two FrameSets, or to append extra axes -* to every Frame in a FrameSet. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the FrameSet. -c iframe -f IFRAME = INTEGER (Given) -* The index of the Frame within the FrameSet which describes -* the coordinate system upon which the new one is to be based. -* This value should lie in the range from 1 to the number of -* Frames already in the FrameSet (as given by its Nframe -* attribute). As a special case, AST__ALLFRAMES may be supplied, -* in which case the axes defined by the supplied Frame are appended -* to every Frame in the FrameSet (see the Notes section for details). -c map -f MAP = INTEGER (Given) -* Pointer to a Mapping which describes how to convert -* coordinates from the old coordinate system (described by the -c Frame with index "iframe") into coordinates in the new -f Frame with index IFRAME) into coordinates in the new -* system. The Mapping's forward transformation should perform -* this conversion, and its inverse transformation should -* convert in the opposite direction. The supplied Mapping is ignored -c if parameter "iframe"is equal to AST__ALLFRAMES. -f if parameter IFRAME is equal to AST__ALLFRAMES. -c frame -f FRAME = INTEGER (Given) -* Pointer to a Frame that describes the new coordinate system. -* Any class of Frame may be supplied (including Regions and -* FrameSets). -* -c This function may also be used to merge two FrameSets by -c supplying a pointer to a second FrameSet for this parameter -f This routine may also be used to merge two FrameSets by -f supplying a pointer to a second FrameSet for this argument -* (see the Notes section for details). -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -* - Deep copies of the supplied -c "mapping" and "frame" -f MAPPING and FRAME -* objects are stored within the modified FrameSet. So any changes made -* to the FrameSet after calling this method will have no effect on the -* supplied Mapping and Frame objects. -* - A value of AST__BASE or AST__CURRENT may be given for the -c "iframe" parameter to specify the base Frame or the current -f IFRAME argument to specify the base Frame or the current -* Frame respectively. -c - This function sets the value of the Current attribute for the -f - This routine sets the value of the Current attribute for the -* FrameSet so that the new Frame subsequently becomes the current -* Frame. -* - The number of input coordinate values accepted by the supplied -* Mapping (its Nin attribute) must match the number of axes in the -c Frame identified by the "iframe" parameter. Similarly, the -f Frame identified by the IFRAME argument. Similarly, the -* number of output coordinate values generated by this Mapping -* (its Nout attribute) must match the number of axes in the new -* Frame. -* - As a special case, if a pointer to a FrameSet is given for the -c "frame" parameter, this is treated as a request to merge a pair of -f FRAME argument, this is treated as a request to merge a pair of -* FrameSets. This is done by appending all the new Frames (in the -c "frame" FrameSet) to the original FrameSet, while preserving -f FRAME FrameSet) to the original FrameSet, while preserving -* their order and retaining all the inter-relationships -* (i.e. Mappings) between them. The two sets of Frames are -* inter-related within the merged FrameSet by using the Mapping -* supplied. This should convert between the Frame identified by -c the "iframe" parameter (in the original FrameSet) and the current -c Frame of the "frame" FrameSet. This latter Frame becomes the -f the IFRAME argument (in the original FrameSet) and the current -f Frame of the FRAME FrameSet. This latter Frame becomes the -* current Frame in the merged FrameSet. -* - As another special case, if a value of AST__ALLFRAMES is supplied -* for parameter -c "iframe", -f IFRAME, -* then the supplied Mapping is ignored, and the axes defined by the -* supplied Frame are appended to each Frame in the FrameSet. In detail, -* each Frame in the FrameSet is replaced by a CmpFrame containing the -* original Frame and the Frame specified by parameter -c "frame". -f FRAME. -* In addition, each Mapping in the FrameSet is replaced by a CmpMap -* containing the original Mapping and a UnitMap in parallel. The Nin and -* Nout attributes of the UnitMap are set equal to the number of axes -* in the supplied Frame. Each new CmpMap is simplified using -c astSimplify -f AST_SIMPLIFY -* before being stored in the FrameSet. - -*-- -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to Frame identified by "iframe" */ - AstFrameSet *frameset; /* Pointer to new FrameSet (if given) */ - AstMapping *inode_map; /* Temporarily saved Mapping pointer */ - AstMapping *map; /* The supplied Mapping */ - AstMapping *next_map; /* Temporarily saved Mapping pointer */ - int current; /* Current Frame index in merged FrameSet */ - int current_node; /* Node number for current Frame */ - int ifr; /* Loop counter for Frames */ - int inode; /* Loop counter for nodes */ - int inode_invert; /* Temporarily saved invert flag value */ - int inode_link; /* Temporarily saved link value */ - int naxes; /* Number of Frame axes */ - int ncoord; /* Number of Mapping coordinates per point */ - int next; /* Number of next node in path */ - int next_invert; /* Temporarily saved invert flag value */ - int next_link; /* Temporarily saved link value */ - int nframe; /* Number of Frames in merged FrameSet */ - int nnode; /* Number of nodes in merged FrameSet */ - int node_zero; /* Location of "node zero" after merging */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* First handle cases where we are appending axes to the existing - Frames in a FrameSet. */ - if( iframe == AST__ALLFRAMES ) { - AppendAxes( this, frame, status ); - return; - } - -/* Now handle cases where we are adding a new Frame into the FrameSet. - Initialise variables to avoid "used of uninitialised variable" - messages from dumb compilers. */ - inode_map = NULL; - next_map = NULL; - inode_invert = 0; - next = 0; - next_invert = 0; - next_link = 0; - -/* If a FrameSet was supplied instead of a Mapping, use the Mapping from - its base Frame to its current Frame. */ - if( astIsAFrameSet( map0 ) ) { - map = astGetMapping( map0, AST__BASE, AST__CURRENT ); - } else { - map = astClone( map0 ); - } - -/* Validate and translate the Frame index supplied. */ - iframe = astValidateFrameIndex( this, iframe, "astAddFrame" ); - -/* Obtain a pointer to the Frame from which the new coordinate system - will be derived and determine how many axes it has. Annul the Frame - pointer afterwards. */ - if ( astOK ) { - fr = astGetFrame( this, iframe ); - naxes = astGetNaxes( fr ); - fr = astAnnul( fr ); - -/* Obtain the number of input coordinate values per point for the - Mapping supplied and check that this matches the number of axes - obtained above. Report an error if it does not. */ - ncoord = astGetNin( map ); - if ( astOK && ( naxes != ncoord ) ) { - astError( AST__NCPIN, "astAddFrame(%s): Bad number of %s input " - "coordinate values (%d).", status, astGetClass( this ), - astGetClass( map ), ncoord ); - astError( AST__NCPIN, "The %s given should accept %d coordinate " - "value%s for each input point.", status, astGetClass( map ), naxes, - ( naxes == 1 ) ? "" : "s" ); - } - } - -/* Similarly, obtain the number of output coordinate values per point - for the Mapping and check that this equals the number of axes for - the Frame supplied. Report an error if necessary. */ - if ( astOK ) { - ncoord = astGetNout( map ); - naxes = astGetNaxes( frame ); - if ( astOK && ( ncoord != naxes ) ) { - astError( AST__NCPIN, "astAddFrame(%s): Bad number of %s output " - "coordinate values (%d).", status, astGetClass( this ), - astGetClass( map ), ncoord ); - astError( AST__NCPIN, "The %s given should generate %d " - "coordinate value%s for each output point.", status, - astGetClass( map ), naxes, ( naxes == 1 ) ? "" : "s" ); - } - } - -/* Normal Frame supplied. */ -/* ====================== */ -/* Check that the Frame supplied is not a FrameSet (handling a - FrameSet is a special case which is addressed later). */ - if ( !astIsAFrameSet( frame ) && astOK ) { - -/* Increase the size of the FrameSet's arrays to accommodate one new - Frame. */ - this->frame = astGrow( this->frame, this->nframe + 1, - sizeof( AstFrame * ) ); - this->varfrm = astGrow( this->varfrm, this->nframe + 1, - sizeof( int ) ); - this->node = astGrow( this->node, this->nframe + 1, sizeof( int ) ); - this->map = astGrow( this->map, this->nnode, sizeof( AstMapping * ) ); - this->link = astGrow( this->link, this->nnode, sizeof( int ) ); - this->invert = astGrow( this->invert, this->nnode, sizeof( int ) ); - if ( astOK ) { - -/* Copy pointers to the Frame and Mapping supplied and store these pointers - in the FrameSet arrays. */ - this->frame[ this->nframe ] = astCopy( frame ); - this->map[ this->nnode - 1 ] = astCopy( map ); - -/* Indicate the Frame does not reflect the variant Mappings of any other - Frame. */ - this->varfrm[ this->nframe ] = 0; - -/* Associate the Frame with the Mapping via the "node" array. */ - this->node[ this->nframe ] = this->nnode; - -/* Add a "link" value which identifies the node from which the new - node is derived and store the current value of the Invert attribute - for the Mapping. */ - this->link[ this->nnode - 1 ] = this->node[ iframe - 1 ]; - this->invert[ this->nnode - 1 ] = astGetInvert( map ); - -/* If successful, increment the FrameSet's Frame and node counts and - set the Current attribute so that the new Frame becomes the current - Frame. */ - if ( astOK ) { - this->nframe++; - this->nnode++; - astSetCurrent( this, this->nframe ); - -/* If an error occurred while filling the FrameSet's arrays, clear any values - that may have been added, annulling any copied pointers. */ - } else { - this->frame[ this->nframe ] = - astAnnul( this->frame[ this->nframe ] ); - this->node[ this->nframe ] = -1; - this->map[ this->nnode - 1 ] = - astAnnul( this->map[ this->nnode - 1 ] ); - this->link[ this->nnode - 1 ] = -1; - } - } - -/* FrameSet supplied. */ -/* ================== */ -/* If the Frame supplied is a FrameSet, we handle this as a special - case by merging the two FrameSets (so that the final result - contains references to all the Frames from both FrameSets). */ - } else if ( astOK ) { - -/* Obtain a pointer to the FrameSet structure containing the new Frame - references and calculate how many Frames and nodes the combined - FrameSet will contain. */ - frameset = (AstFrameSet *) frame; - nframe = this->nframe + frameset->nframe; - nnode = this->nnode + frameset->nnode; - -/* Extend the original FrameSet's arrays to accommodate the new Frames - and nodes. */ - this->frame = astGrow( this->frame, nframe, sizeof( AstFrame * ) ); - this->varfrm = astGrow( this->varfrm, nframe, sizeof( int ) ); - this->node = astGrow( this->node, nframe, sizeof( int ) ); - this->map = astGrow( this->map, nnode - 1, sizeof( AstMapping * ) ); - this->link = astGrow( this->link, nnode - 1, sizeof( int ) ); - this->invert = astGrow( this->invert, nnode - 1, sizeof( int ) ); - -/* If OK, loop to transfer the new Frame data into the new array - elements, cloning each Frame pointer. Increment each "node" value - to allow for the new node numbering which will apply when the new - node data is appended to the new arrays. */ - if ( astOK ) { - for ( ifr = 1; ifr <= frameset->nframe; ifr++ ) { - this->frame[ this->nframe + ifr - 1 ] = - astCopy( frameset->frame[ ifr - 1 ] ); - this->node[ this->nframe + ifr - 1 ] = - frameset->node[ ifr - 1 ] + this->nnode; - if( frameset->varfrm[ ifr - 1 ] > 0 ) { - this->varfrm[ this->nframe + ifr - 1 ] = - frameset->varfrm[ ifr - 1 ] + this->nframe; - } else { - this->varfrm[ this->nframe + ifr - 1 ] = 0; - } - } - -/* Similarly, transfer the new node data, cloning each Mapping - pointer. Increment each "link" value to allow for the new node - numbering. */ - for ( inode = 1; inode < frameset->nnode; inode++ ) { - this->map[ this->nnode + inode - 1 ] = - astCopy( frameset->map[ inode - 1 ] ); - this->link[ this->nnode + inode - 1 ] = - frameset->link[ inode - 1 ] + this->nnode; - this->invert[ this->nnode + inode - 1 ] = - frameset->invert[ inode - 1 ]; - } - -/* In transferring the node data (above), we left an empty array - element which will later be filled with data corresponding to node - zero in the new FrameSet (there are no data to be copied for this - node). Initialise the data for this element to null values. */ - this->map[ this->nnode - 1 ] = NULL; - this->link[ this->nnode - 1 ] = -1; - this->invert[ this->nnode - 1 ] = -1; - -/* Determine which is the current Frame in the new FrameSet and - convert this into the corresponding Frame number in the combined - one. */ - current = astGetCurrent( frameset ) + this->nframe; - -/* We must now form a new link between this Frame and Frame "iframe" - (using the Mapping supplied) in order to inter-relate the Frames - from the two FrameSets. However, this cannot be done immediately - because in general the node corresponding to Frame "current" will - already have a link pointing to another node. Moreover, the node - which was originally node zero (in the new FrameSet) still has - no data in our merged FrameSet. - - To overcome this, we must re-structure the links within the - transferred data. We do this by starting at the node corresponding - to Frame "current" and working back through each link until the - original node zero is reached. At each step along this path, we - reverse the direction of the link. This involves shifting the - associated data by one step along the path, so that it becomes - associated with the next node. This results in the final - (initialised-to-null) node acquiring some data, and the starting - node being left free to receive our new link. - - We compensate for reversing the links by reversing the sense of the - "invert" flag associated with each Mapping along the path, so that - the overall structure of the FrameSet is unchanged. */ - -/* Identify the starting node (the one corresponding to Frame - "current"). */ - if ( astOK ) { - current_node = this->node[ current - 1 ]; - -/* Obtain the value which a "link" element will now have if it - originally identified node zero in the new FrameSet. We will use - this value to detect the end of the path. */ - node_zero = this->nnode; - -/* If we are not already at "node zero", save the data for the current - node. */ - if ( current_node != node_zero ) { - inode_map = this->map[ current_node - 1 ]; - inode_link = this->link[ current_node - 1 ]; - inode_invert = this->invert[ current_node - 1 ]; - -/* Reset the node's data to null values (pending setting up the new - link using the Mapping supplied). */ - this->map[ current_node - 1 ] = NULL; - this->link[ current_node - 1 ] = -1; - this->invert[ current_node - 1 ] = -1; - -/* Identify the next node in the path. */ - next = inode_link; - } - -/* Follow the path until "node zero" is reached. */ - inode = current_node; - while( inode != node_zero ) { - -/* If the next node on the path is not "node zero", save its data - (because we are about to write over it). */ - if ( next != node_zero ) { - next_map = this->map[ next - 1 ]; - next_link = this->link[ next - 1 ]; - next_invert = this->invert[ next - 1 ]; - } - -/* Reverse the link from the current node to the "next" node. This - involves transferring the "map" and "invert" values to the "next" - node and inverting the sense of the latter to compensate. Make the - "next" node point back to the current one. */ - this->map[ next - 1 ] = inode_map; - this->link[ next - 1 ] = inode; - this->invert[ next - 1 ] = !inode_invert; - -/* Move on to consider the next node. */ - inode = next; - -/* If we have not reached "node zero" yet, transfer the node data we - saved above into the variables from which it will be transferred to - the following node on the next pass through this loop. */ - if ( inode != node_zero ) { - inode_map = next_map; - inode_link = next_link; - inode_invert = next_invert; - -/* Identify the node that follows the next one. */ - next = inode_link; - } - } - -/* Once the necessary links have been re-structured, establish the new - link that inter-relates the Frames from the two FrameSets. */ - this->map[ current_node - 1 ] = astCopy( map ); - this->link[ current_node - 1 ] = this->node[ iframe - 1 ]; - this->invert[ current_node - 1 ] = astGetInvert( map ); - } - -/* If successful, update the Frame and node counts and make the - appropriate Frame current. */ - if ( astOK ) { - this->nframe = nframe; - this->nnode = nnode; - astSetCurrent( this, current ); - -/* If an error occurred, loop through all the new Frame and node array - elements and clear them, ensuring that any remaining Object - pointers are annulled. */ - } else { - for ( ifr = 1; ifr <= frameset->nframe; ifr++ ) { - this->frame[ this->nframe + ifr - 1 ] = - astAnnul( this->frame[ this->nframe + ifr - 1 ] ); - this->node[ this->nframe + ifr - 1 ] = -1; - this->varfrm[ this->nframe + ifr - 1 ] = 0; - } - for ( inode = 0; inode < frameset->nnode; inode++ ) { - this->map[ this->nnode + inode - 1 ] = - astAnnul( this->map[ this->nnode + inode - 1 ] ); - this->link[ this->nnode + inode - 1 ] = -1; - this->invert[ this->nnode + inode - 1 ] = -1; - } - } - } - } - -/* Annul the local pointer to the supplied Mapping. */ - map = astAnnul( map ); -} - -static void AddVariant( AstFrameSet *this, AstMapping *map, - const char *name, int *status ) { -/* -*++ -* Name: -c astAddVariant -f AST_ADDVARIANT - -* Purpose: -* Store a new variant Mapping for the current Frame in a FrameSet. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frameset.h" -c void astAddVariant( AstFrameSet *this, AstMapping *map, -c const char *name ) -f CALL AST_ADDVARIANT( THIS, MAP, NAME, STATUS ) - -* Class Membership: -* FrameSet method. - -* Description: -c This function -f This routine -* allows a new variant Mapping to be stored with the current Frame -* in a FrameSet. See the "Variant" attribute for more details. It can -* also be used to rename the currently selected variant Mapping. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the FrameSet. -c map -f MAP = INTEGER (Given) -* Pointer to a Mapping which describes how to convert -* coordinates from the current Frame to the new variant of the -* current Frame. If -c NULL -f AST__NULL -* is supplied, then the name associated with the currently selected -* variant of the current Frame is set to the value supplied for -c "name", but no new variant is added. -f NAME, but no new variant is added. -c name -f NAME = CHARACTER * ( * ) (Given) -* The name to associate with the new variant Mapping (or the currently -* selected variant Mapping if -c "map" is NULL). -f MAP is AST__NULL). -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -* - The newly added Variant becomes the current variant on exit (this is -* equivalent to setting the Variant attribute to the value supplied for -c "name). -f NAME). -* - An error is reported if a variant with the supplied name already -* exists in the current Frame. -* - An error is reported if the current Frame is a mirror for the -* variant Mappings in another Frame. This is only the case if the -c astMirrorVariants function -f AST_MIRRORVARIANTS routine -* has been called to make the current Frame act as a mirror. - -*-- -*/ - -/* Local Variables: */ - AstCmpMap *map2; - AstFrame *frm; - AstFrame *tfrm; - AstFrame *vfrm; - AstFrameSet *tfs; - AstFrameSet *vfs; - AstMapping *map1; - AstMapping *map3; - char *myname; - const char *dom; - int icur; - int ifrm; - int new; - int nfrm; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get the one-based index of the current Frame. */ - icur = astGetCurrent( this ); - -/* Report an error if the current Frame is just a mirror. */ - if( this->varfrm[ icur - 1 ] > 0 && astOK ) { - astError( AST__MIRRO, "astAddVariant(%s): Illegal attempt to " - "add a variant Mapping to a mirror Frame (programming " - "error).", status, astGetClass( this ) ); - } - -/* Get a copy of the supplied string and clean it. */ - myname = astStore( NULL, name, strlen( name ) + 1 ); - astRemoveLeadingBlanks( myname ); - astChrCase( NULL, myname, 1, 0 ); - if( astOK ) { - myname[ astChrLen( myname ) ] = 0; - -/* Get the Variants FrameSet for the current Frame in "this". */ - frm = astGetFrame( this, icur ); - vfs = astGetFrameVariants( frm ); - -/* If current Frame of this has no Variant FrameSet, create a Variants - FrameSet containing a copy of the current Frame (retain its Domain - as the default variant name). */ - if( !vfs ) { - tfrm = astCopy( frm ); - vfs = astFrameSet( tfrm, " ", status ); - tfrm = astAnnul( tfrm ); - new = 1; - } else { - new = 0; - } - -/* Check the Variants FrameSet does not already contain a Frame with - a Domain equal to the supplied name. */ - nfrm = astGetNframe( vfs ); - for( ifrm = 0; ifrm < nfrm && astOK; ifrm++ ) { - vfrm = astGetFrame( vfs, ifrm + 1 ); - dom = astGetDomain( vfrm ); - if( astOK && !strcmp( dom, myname ) ) { - astError( AST__BDVNM, "astAddVariant(%s): Cannot add a " - "variant %s Frame with name '%s' because one " - "already exists in the %s (programming " - "error).", status, astGetClass( this ), - astGetDomain( frm ), myname, astGetClass( this ) ); - } - vfrm = astAnnul( vfrm ); - } - -/* If no Mapping was supplied, just set the name of the currently - selected variant. The names are stored in the Domain attribute of - the Frames in the variants FrameSet, so set teh DOmain for the current - Frame. */ - if( !map ){ - vfrm = astGetFrame( vfs, AST__CURRENT ); - astSetDomain( vfrm, name ); - vfrm = astAnnul( vfrm ); - -/* If a Mapping was supplied.... */ - } else { - -/* Get the Mapping from the current Frame in the variants FrameSet to the - current Frame in "this". Temporarily match the Domains so that - astConvert can work. */ - vfrm = astGetFrame( vfs, AST__CURRENT ); - dom = astGetDomain( frm ); - if( dom ) dom = astStore( NULL, dom, strlen( dom ) + 1 ); - astSetDomain( frm, astGetDomain( vfrm ) ); - tfs = astConvert( vfrm, frm, "" ); - astSetDomain( frm, dom ); - if( tfs ) { - map1 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); - tfs = astAnnul( tfs ); - -/* Concatenate it with the supplied Mapping to get the mapping from the - current Frame in the Variants FrameSet to the new variant Frame. */ - map2 = astCmpMap( map1, map, 1, " ", status ); - map3 = astSimplify( map2 ); - -/* Add a copy of parent Frame into Variants FrameSet, using the above - mapping to connect it to the original current Variants Frame. Set - its Domain to the supplied name. Re-instate the original current Frame - afterwards. Remove the variant frame info before adding it. */ - (void) astAnnul( vfrm ); - vfrm = astCopy( frm ); - astSetFrameVariants( vfrm, NULL ); - astSetDomain( vfrm, name ); - icur = astGetCurrent( vfs ); - astAddFrame( vfs, AST__CURRENT, map3, vfrm ); - astSetCurrent( vfs, icur ); - -/* Free resources. */ - map1 = astAnnul( map1 ); - map2 = astAnnul( map2 ); - map3 = astAnnul( map3 ); - -/* Report an error if a Mapping cannot be found from the new variant Frame - to the current Frame in "this". */ - } else if( astOK ) { - astError( AST__INTER, "astAddVariant(%s): Cannot convert " - "from a %s with Domain '%s' to a %s with Domain " - "'%s' (internal programming error).", status, - astGetClass( this ), astGetClass( vfrm ), - astGetDomain( vfrm ), astGetClass( frm ), - astGetDomain( frm ) ); - } - -/* Free resources. */ - dom = astFree( (void *) dom ); - vfrm = astAnnul( vfrm ); - } - -/* If all is well, and the Variants FrameSet is new, store a pointer to - it in the current Frame of "this". */ - if( new ) astSetFrameVariants( frm, vfs ); - -/* Make the new Variant the current variant. */ - if( map ) astSetVariant( this, name ); - -/* Free remaining resources. */ - frm = astAnnul( frm ); - vfs = astAnnul( vfs ); - } - myname = astFree( myname ); -} - -static double Angle( AstFrame *this_frame, const double a[], - const double b[], const double c[], int *status ) { -/* -* Name: -* Angle - -* Purpose: -* Calculate the angle subtended by two points at a third point. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* double Angle( AstFrame *this, const double a[], const double b[], -* const double c[], int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astAngle -* method inherited from the Frame class). - -* Description: -* This function finds the angle at point B between the line joining points -* A and B, and the line joining points C and B. These lines will in fact be -* geodesic curves appropriate to the Frame in use. For instance, in -* SkyFrame, they will be great circles. - -* Parameters: -* this -* Pointer to the Frame. -* a -* An array of double, with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the first point. -* b -* An array of double, with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the second point. -* c -* An array of double, with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the third point. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* astAngle -* The angle in radians, from the line AB to the line CB. If the -* Frame is 2-dimensional, it will be in the range $\pm \pi$, -* and positive rotation is in the same sense as rotation from -* the positive direction of axis 2 to the positive direction of -* axis 1. If the Frame has more than 2 axes, a positive value will -* always be returned in the range zero to $\pi$. - -* Notes: -* - A value of AST__BAD will also be returned if points A and B are -* co-incident, or if points B and C are co-incident. -* - A value of AST__BAD will also be returned if this function is -* invoked with the AST error status set, or if it should fail for -* any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double result; /* Value to return */ - -/* Check the global error status. */ - if ( !astOK ) return AST__BAD; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astAngle method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astAngle( fr, a, b, c ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = AST__BAD; - -/* Return the result. */ - return result; -} - -static void AppendAxes( AstFrameSet *this, AstFrame *frame, int *status ) { -/* -* Name: -* AppendAxes - -* Purpose: -* Append axes to every Frame in a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void AppendAxes( AstFrameSet *this, AstFrame *frame, int *status ) - -* Class Membership: -* FrameSet member function - -* Description: -* This function replaces every Frame in the FrameSet with a CmpFrame -* holding the original Frame and the supplied Frame. It also replaces -* every Mapping in the FrameSet with a parallel CmpMap holding the -* original Mapping and a UnitMap. The Nin and Nout attributes of every -* UnitMap are equal to the number of axes in the supplied Frame. Each -* CmpMap is simplified before being stored in the FrameSet. - - -* Parameters: -* this -* Pointer to the Frame. -* frame -* Pointer to a Frame holding the new axes to add to every Frame in -* the FrameSet. -* status -* Pointer to the inherited status variable. - -*/ - -/* Local Variables: */ - AstCmpFrame *frm; /* Pointer to new Frame */ - AstCmpMap *map; /* UnitMap to new Mapping */ - AstUnitMap *umap; /* UnitMap to feed the new axes */ - int iframe; /* Frame index */ - int imap; /* Mapping index */ - int inv_orig; /* Original value of Invert attribute */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Loop round every Frame in the FrameSet. */ - for ( iframe = 0; iframe < this->nframe; iframe++ ) { - -/* Create a CmpFrame holding the original Frame and the new Frame. */ - frm = astCmpFrame( this->frame[ iframe ], frame, " ", status ); - -/* Annul the original Frame pointer and store the new CmpFrame pointer. */ - (void) astAnnul( this->frame[ iframe ] ); - this->frame[ iframe ] = (AstFrame *) frm; - } - -/* Create a UnitMap with the number of inputs and outputs equal to the - number of axes in the supplied Frame. */ - umap = astUnitMap( astGetNaxes( frame ), " ", status ); - -/* Loop round every Mapping in the FrameSet. */ - for ( imap = 0; imap < this->nnode - 1; imap++ ) { - -/* The Invert attribute of the Mapping may have been changed via a - different pointer since it was first added into the FrameSet. To - ensure that the FrameSet continues to behave as was originally - intended, we set the Invert attribute back to the value it had when - the Mapping was first added into the FrameSet. First, note the - current value of the Invert flag so that it can be re-instated later. */ - inv_orig = astGetInvert( this->map[ imap ] ); - astSetInvert( this->map[ imap ], this->invert[ imap ] ); - -/* Create a parallel CmpMap holding the original Mapping and the UnitMap. */ - map = astCmpMap( this->map[ imap ], umap, 0, " ", status ); - -/* Re-instate the original value for the Invert flag, and then annul the - original Mapping pointer. */ - astSetInvert( this->map[ imap ], inv_orig ); - (void) astAnnul( this->map[ imap ] ); - -/* Simplify the new Mapping, and store it in the FrameSet. */ - this->map[ imap ] = astSimplify( map ); - -/* Store a copy of the Invert attribute that should be used with this - Mapping within the FrameSet (just in case it is modified via some - excternal reference). */ - this->invert[ imap ] = astGetInvert( this->map[ imap ] ); - -/* Annul the un-simplified Mapping pointer. */ - map = astAnnul( map ); - } - -/* Annul the UnitMap pointer. */ - umap = astAnnul( umap ); -} - -static double AxAngle( AstFrame *this_frame, const double a[], const double b[], int axis, int *status ) { -/* -* Name: -* AxAngle - -* Purpose: -* Returns the angle from an axis, to a line through two points. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* double AxAngle( AstFrame *this, const double a[], const double b[], int axis, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astAxAngle -* method inherited from the Frame class). - -* Description: -* This function finds the angle, as seen from point A, between the positive -* direction of a specified axis, and the geodesic curve joining point -* A to point B. - -* Parameters: -* this -* Pointer to the Frame. -* a -* An array of double, with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the first point. -* b -* An array of double, with one element for each Frame axis -* (Naxes attribute) containing the coordinates of the second point. -* axis -* The number of the Frame axis from which the angle is to be -* measured (one-based). -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The angle in radians, from the positive direction of the -* specified axis, to the line AB. If the Frame is 2-dimensional, -* it will be in the range $\pm \pi$, and positive rotation is in -* the same sense as rotation from the positive direction of axis 2 -* to the positive direction of axis 1. If the Frame has more than 2 -* axes, a positive value will always be returned in the range zero -* to $\pi$. - -* Notes: -* - The geodesic curve used by this function is the path of -* shortest distance between two points, as defined by the -* astDistance function. -* - This function will return "bad" coordinate values (AST__BAD) -* if any of the input coordinates has this value, or if the require -* position angle is undefined. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double result; /* Value to return */ - -/* Check the global error status. */ - if ( !astOK ) return AST__BAD; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis - 1, 1, "astAxAngle" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astAxAngle method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astAxAngle( fr, a, b, axis ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = AST__BAD; - -/* Return the result. */ - return result; -} - -static double AxDistance( AstFrame *this_frame, int axis, double v1, double v2, int *status ) { -/* -* Name: -* AxDistance - -* Purpose: -* Find the distance between two axis values. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* double AxDistance( AstFrame *this, int axis, double v1, double v2, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astAxDistance -* method inherited from the Frame class). - -* Description: -* This function returns a signed value representing the axis increment -* from axis value v1 to axis value v2. -* -* For a simple Frame, this is a trivial operation returning the -* difference between the two axis values. But for other derived classes -* of Frame (such as a SkyFrame) this is not the case. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The index of the axis to which the supplied values refer. The -* first axis has index 1. -* v1 -* The first axis value. -* v2 -* The second axis value. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The distance between the two axis values. - -* Notes: -* - This function will return a "bad" result value (AST__BAD) if -* any of the input vaues has this value. -* - A "bad" value will also be returned if this function is -* invoked with the AST error status set, or if it should fail for -* any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double result; /* Value to return */ - -/* Check the global error status. */ - if ( !astOK ) return AST__BAD; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis - 1, 1, "astAxDistance" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astAxDistance method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astAxDistance( fr, axis, v1, v2 ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = AST__BAD; - -/* Return the result. */ - return result; -} - -static void AxNorm( AstFrame *this_frame, int axis, int oper, int nval, - double *values, int *status ){ -/* -* Name: -* AxNorm - -* Purpose: -* Normalise an array of axis values. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void AxNorm( AstFrame *this, int axis, int oper, int nval, -* double *values, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astAxNorm -* method inherited from the Frame class). - -* Description: -* This function modifies a supplied array of axis values so that -* they are normalised in the manner indicated by parameter "oper". -* -* No normalisation is possible for a simple Frame and so the supplied -* values are returned unchanged. However, this may not be the case for -* specialised sub-classes of Frame. For instance, a SkyFrame has a -* discontinuity at zero longitude and so a longitude value can be -* expressed in the range [-Pi,+PI] or the range [0,2*PI]. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The index of the axis to which the supplied values refer. The -* first axis has index 1. -* oper -* Indicates the type of normalisation to be applied. If zero is -* supplied, the normalisation will be the same as that performed by -* function astNorm. If 1 is supplied, the normalisation will be -* chosen automatically so that the resulting list has the smallest -* range. -* nval -* The number of points in the values array. -* values -* On entry, the axis values to be normalised. Modified on exit to -* hold the normalised values. -* status -* Pointer to the inherited status variable. - -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis - 1, 1, "astAxNorm" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astAxNorm method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astAxNorm( fr, axis, oper, nval, values ); - fr = astAnnul( fr ); -} - -static double AxOffset( AstFrame *this_frame, int axis, double v1, double dist, int *status ) { -/* -* Name: -* AxOffset - -* Purpose: -* Add an increment onto a supplied axis value. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* double AxOffset( AstFrame *this, int axis, double v1, double dist, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astAxOffset -* method inherited from the Frame class). - -* Description: -* This function returns an axis value formed by adding a signed axis -* increment onto a supplied axis value. -* -* For a simple Frame, this is a trivial operation returning the -* sum of the two supplied values. But for other derived classes -* of Frame (such as a SkyFrame) this is not the case. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The index of the axis to which the supplied values refer. The -* first axis has index 1. -* v1 -* The original axis value. -* dist -* The axis increment to add to the original axis value. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The incremented axis value. - -* Notes: -* - This function will return a "bad" result value (AST__BAD) if -* any of the input vaues has this value. -* - A "bad" value will also be returned if this function is -* invoked with the AST error status set, or if it should fail for -* any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double result; /* Value to return */ - -/* Check the global error status. */ - if ( !astOK ) return AST__BAD; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis - 1, 1, "astAxOffset" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astAxOffset method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astAxOffset( fr, axis, v1, dist ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = AST__BAD; - -/* Return the result. */ - return result; -} - -static AstObject *Cast( AstObject *this_object, AstObject *obj, int *status ) { -/* -* Name: -* Cast - -* Purpose: -* Cast an Object into an instance of a sub-class. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstObject *Cast( AstObject *this, AstObject *obj, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astCast -* method inherited from the Frame class). - -* Description: -* This function returns a deep copy of an ancestral component of the -* supplied object. The required class of the ancestral component is -* specified by another object. Specifically, if "this" and "new" are -* of the same class, a copy of "this" is returned. If "this" is an -* instance of a subclass of "obj", then a copy of the component -* of "this" that matches the class of "obj" is returned. Otherwise, -* a NULL pointer is returned without error. - -* Parameters: -* this -* Pointer to the Object to be cast. -* obj -* Pointer to an Object that defines the class of the returned Object. -* The returned Object will be of the same class as "obj". - -* Returned Value: -* A pointer to the new Object. NULL if "this" is not a sub-class of -* "obj", or if an error occurs. - -* Notes: -* - A NULL pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables; */ - AstFrame *cfrm; - AstObject *new; - astDECLARE_GLOBALS - int generation_gap; - -/* Initialise */ - new = NULL; - -/* Check inherited status */ - if( !astOK ) return new; - -/* Get a pointer to the thread specific global data structure. */ - astGET_GLOBALS(NULL); - -/* See how many steps up the class inheritance ladder it is from "obj" - to this class (FrameSet). A positive value is returned if FrameSet - is a sub-class of "obj". A negative value is returned if "obj" is - a sub-class of FrameSet. Zero is returned if "obj" is a FrameSet. - AST__COUSIN is returned if "obj" is not on the same line of descent - as FrameSet. */ - generation_gap = astClassCompare( (AstObjectVtab *) &class_vtab, - astVTAB( obj ) ); - -/* If "obj" is a FrameSet or a sub-class of FrameSet, we can cast by - truncating the vtab for "this" so that it matches the vtab of "obJ", - and then taking a deep copy of "this". */ - if( generation_gap <= 0 && generation_gap != AST__COUSIN ) { - new = astCastCopy( this_object, obj ); - -/* If "obj" is not a FrameSet or a sub-class of FrameSet (e.g. a Frame or - some sub-class of Frame), we attempt to cast the current Frame into - the class indicated by "obj". */ - } else { - cfrm = astGetFrame( (AstFrameSet *) this_object, AST__CURRENT ); - new = astCast( cfrm, obj ); - cfrm = astAnnul( cfrm ); - } - -/* Return the new pointer. */ - return new; -} - -static double Centre( AstFrame *this_frame, int axis, double value, double gap, int *status ) { -/* -* Name: -* Centre - -* Purpose: -* Find a "nice" central value for tabulating Frame axis values. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* double Centre( AstFrame *this_frame, int axis, double value, -* double gap, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astCentre method -* inherited from the Frame class). - -* Description: -* This function returns an axis value which produces a nice formatted -* value suitable for a major tick mark on a plot axis, close to the -* supplied axis value. - -* Parameters: -* this -* Pointer to the Frame. -* axis -* The number of the axis (zero-based) for which a central value -* is to be found. -* value -* An arbitrary axis value in the section that is being plotted. -* gap -* The gap size. - -* Returned Value: -* The nice central axis value. - -* Notes: -* - A value of zero is returned if the supplied gap size is zero. -* - A value of zero will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double result; /* Value to return */ - -/* Check the global error status. */ - if ( !astOK ) return 0.0; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis, 1, "astCentre" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astCentre method to obtain the required value. Annul the - Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astCentre( fr, axis, value, gap ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = 0.0; - -/* Return the result. */ - return result; -} - -static void CheckPerm( AstFrame *this_frame, const int *perm, const char *method, int *status ) { -/* -* Name: -* CheckPerm - -* Purpose: -* Check that an array contains a valid permutation. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void CheckPerm( AstFrame *this, const int *perm, const char *method, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astCheckPerm -* method inherited from the Frame class). - -* Description: -* This function checks the validity of a permutation array that -* will be used to permute the order of a Frame's axes. If the -* permutation specified by the array is not valid, an error is -* reported and the global error status is set. Otherwise, the -* function returns without further action. - -* Parameters: -* this -* Pointer to the Frame. -* perm -* Pointer to an array of integers with the same number of -* elements as there are axes in the Frame. For each axis, the -* corresponding integer gives the (zero based) axis index to be -* used to identify the information for that axis (using the -* un-permuted axis numbering). To be valid, the integers in -* this array should therefore all lie in the range zero to -* (naxes-1) inclusive, where "naxes" is the number of Frame -* axes, and each value should occur exactly once. -* method -* Pointer to a constant null-terminated character string -* containing the name of the method that invoked this function -* to validate a permutation array. This method name is used -* solely for constructing error messages. -* status -* Pointer to the inherited status variable. - -* Notes: -* - Error messages issued by this function refer to the external -* (public) numbering system used for axes (which is one-based), -* whereas zero-based axis indices are used internally. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astCheckPerm method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astCheckPerm( fr, perm, method ); - fr = astAnnul( fr ); - -} - -static void Clear( AstObject *this_object, const char *attrib, int *status ) { -/* -* Name: -* Clear - -* Purpose: -* Clear attribute values for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void Clear( AstObject *this, const char *attrib, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the public astClear method -* inherited from the Object class). - -* Description: -* This function clears the values of a specified set of attributes -* for a FrameSet. Clearing an attribute cancels any value that has -* previously been explicitly set for it, so that the standard -* default attribute value will subsequently be used instead. This -* also causes the astTest function to return the value zero for -* the attribute, indicating that no value has been set. - -* Parameters: -* this -* Pointer to the FrameSet. -* attrib -* Pointer to a null-terminated character string containing a -* comma-separated list of the names of the attributes to be -* cleared. -* status -* Pointer to the inherited status variable. - -* Notes: -* - This function preserves the integrity of the FrameSet (if -* possible) by appropriately remapping its current Frame to take -* account of its changed attribute values. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - AstFrame *save_frame; /* Saved pointer to integrity Frame */ - AstFrameSet *this; /* Pointer to FrameSet structure */ - const char *save_method; /* Saved pointer to method name */ - int ok; /* Status OK? */ - int save_lost; /* Saved integrity modified flag */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this_object); - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* To allow this function to be invoked recursively, we first save any - existing FrameSet integrity information in local variables. */ - save_frame = integrity_frame; - save_lost= integrity_lost; - save_method = integrity_method; - -/* Set the name of the method being used (for use in error - messages). */ - integrity_method = "astClear"; - -/* Record the initial integrity state of the FrameSet. */ - RecordIntegrity( this, status ); - -/* Invoke the parent astClear method to clear the FrameSet's attribute - values and note if this succeeds. */ - (*parent_clear)( this_object, attrib, status ); - ok = astOK; - -/* Restore the FrameSet's integrity. */ - RestoreIntegrity( this, status ); - -/* If integrity could not be restored, then add contextual error - information. */ - if ( !astOK && ok ) { - astError( astStatus, "Unable to accommodate clearing the \"%s\" " - "attribute(s).", status, attrib ); - } - -/* Restore any saved FrameSet integrity information. */ - integrity_frame = save_frame; - integrity_lost = save_lost; - integrity_method = save_method; -} - -static void ClearAttrib( AstObject *this_object, const char *attrib, int *status ) { -/* -* Name: -* ClearAttrib - -* Purpose: -* Clear an attribute value for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void ClearAttrib( AstObject *this, const char *attrib ) - -* Class Membership: -* FrameSet member function (over-rides the astClearAttrib protected -* method inherited from the Frame class). - -* Description: -* This function clears the value of a specified attribute for a -* FrameSet, so that the default value will subsequently be used. - -* Parameters: -* this -* Pointer to the FrameSet. -* attrib -* Pointer to a null terminated string specifying the attribute -* name. This should be in lower case with no surrounding white -* space. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this_object); -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* Check the attribute name and clear the appropriate attribute. */ - -/* We first handle attributes that apply to the FrameSet as a whole - (rather than to the current Frame). */ - -/* Base. */ -/* ----- */ - if ( !strcmp( attrib, "base" ) ) { - astClearBase( this ); - -/* Current. */ -/* -------- */ -/* Since this determines the choice of current Frame, we must restore - the integrity state of the FrameSet before changing this attribute - and record the new integrity state afterwards. */ - } else if ( !strcmp( attrib, "current" ) ) { - RestoreIntegrity( this, status ); - astClearCurrent( this ); - RecordIntegrity( this, status ); - -/* ID. */ -/* --- */ - } else if ( !strcmp( attrib, "id" ) ) { - astClearID( this ); - -/* Ident. */ -/* ------ */ - } else if ( !strcmp( attrib, "ident" ) ) { - astClearIdent( this ); - -/* Invert. */ -/* ------- */ -/* Since this affects the choice of current Frame, we must restore the - integrity state of the FrameSet before changing this attribute and - record the new integrity state afterwards. */ - } else if ( !strcmp( attrib, "invert" ) ) { - RestoreIntegrity( this, status ); - astClearInvert( this ); - RecordIntegrity( this, status ); - -/* Report. */ -/* ------- */ - } else if ( !strcmp( attrib, "report" ) ) { - astClearReport( this ); - -/* Variant. */ -/* -------- */ - } else if ( !strcmp( attrib, "variant" ) ) { - astClearVariant( this ); - -/* If the name was not recognised, test if it matches any of the - read-only attributes of this class. If it does, then report an - error. */ - } else if ( !strcmp( attrib, "allvariants" ) || - !strcmp( attrib, "class" ) || - !strcmp( attrib, "nframe" ) || - !strcmp( attrib, "nin" ) || - !strcmp( attrib, "nobject" ) || - !strcmp( attrib, "nout" ) || - !strcmp( attrib, "refcount" ) || - !strcmp( attrib, "tranforward" ) || - !strcmp( attrib, "traninverse" ) ) { - astError( AST__NOWRT, "astClear: Invalid attempt to clear the \"%s\" " - "value for a %s.", status, attrib, astGetClass( this ) ); - astError( AST__NOWRT, "This is a read-only attribute." , status); - -/* Pass unrecognised attributes on to the FrameSet's current Frame for - further interpretation. */ - } else { - -/* Force a copy to be made of the current Frame, if needed, to make it - independent of other Frames within the FrameSet. */ - (void) ForceCopy( this, AST__CURRENT, status ); - -/* Obtain a pointer to the current Frame and invoke its astClearAttrib - method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astClearAttrib( fr, attrib ); - fr = astAnnul( fr ); - -/* Note that the current Frame has been modified. */ - integrity_lost = 1; - } -} - -static void ClearBase( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astClearBase - -* Purpose: -* Clear the value of the Base attribute of a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* void astClearBase( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function clears the value of the Base attribute of a -* FrameSet. This value is an index that identifies the base Frame -* for the FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. -*- -*/ - -/* Local Variables: */ - int invert; /* FrameSet is inverted? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Determine if the FrameSet has been inverted. */ - invert = astGetInvert( this ); - -/* If it has not been inverted, clear the base Frame index, otherwise - clear the current Frame index instead. */ - if ( astOK ) *( invert ? &this->current : &this->base ) = -INT_MAX; -} - -static void ClearCurrent( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astClearCurrent - -* Purpose: -* Clear the value of the Current attribute for a FrameSet. - -* Type: -* Protected function. - -* Synopsis: -* #include "frameset.h" -* int astClearCurrent( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function clears the value of the Current attribute for a -* FrameSet. This attribute is an index that identifies the current -* Frame for the FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. -*- -*/ - -/* Local Variables: */ - int invert; /* FrameSet is inverted? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Determine if the FrameSet has been inverted. */ - invert = astGetInvert( this ); - -/* If it has not been inverted, clear the current frame index, - otherwise clear the base Frame index instead. */ - if ( astOK ) *( invert ? &this->base : &this->current ) = -INT_MAX; -} - -static void ClearVariant( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astClearVariant - -* Purpose: -* Clear the value of the Variant attribute of a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* void astClearVariant( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function clears the value of the Variant attribute of a -* FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. -*- -*/ - -/* Local Variables: */ - AstFrame *frm; - int icur; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get the one-based index of the Frame to use. */ - icur = GetVarFrm( this, astGetCurrent( this ), status ); - -/* Get a pointer to the current Frame in the FrameSet. */ - frm = astGetFrame( this, icur ); - -/* Replace any Variants FrameSet in the Frame with a NULL pointer. */ - astSetFrameVariants( frm, NULL ); - -/* Annul the current Frame pointer. */ - frm = astAnnul( frm ); - -} - -static AstMapping *CombineMaps( AstMapping *mapping1, int invert1, - AstMapping *mapping2, int invert2, - int series, int *status ) { -/* -* Name: -* CombineMaps - -* Purpose: -* Combine two Mappings with specified Invert flags into a CmpMap. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstMapping *CombineMaps( AstMapping *mapping1, int invert1, -* AstMapping *mapping2, int invert2, -* int series ) - -* Class Membership: -* FrameSet member function. - -* Description: -* This function combines two Mappings into a CmpMap (compound -* Mapping) as if their Invert flags were set to specified values -* when the CmpMap is created. However, the individual Mappings are -* returned with their Invert flag values unchanged from their -* original state. - -* Parameters: -* mapping1 -* Pointer to the first Mapping. -* invert1 -* The (boolean) Invert flag value required for the first Mapping. -* mapping2 -* Pointer to the second Mapping. -* invert2 -* The (boolean) Invert flag value required for the second Mapping. -* series -* Whether the Mappings are to be combined in series (as opposed to -* in parallel). - -* Returned Value: -* A pointer to the resulting compound Mapping (a CmpMap). - -* Notes: -* - This function is a wrap-up for the astCmpMap constructor and -* temporarily assigns the required Invert flag values while -* creating the required CmpMap. However, it also takes account of -* the possibility that the two Mapping pointers supplied may point -* at the same Mapping. -* - A null Object pointer (AST__NULL) will be returned if this -* function is invoked with the AST error status set, or if it -* should fail for any reason. -*/ - -/* Local Variables: */ - AstMapping *map1; /* First temporary Mapping pointer */ - AstMapping *map2; /* Second temporary Mapping pointer */ - AstMapping *result; /* Pointer to result Mapping */ - int copy; /* Copy needed? */ - int inv1; /* First original Invert flag value */ - int inv2; /* Second original Invert flag value */ - int set1; /* First Invert flag originally set? */ - int set2; /* Second Invert flag originally set? */ - -/* Initialise */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Limit incoming values to 0 or 1. */ - invert1 = ( invert1 != 0 ); - invert2 = ( invert2 != 0 ); - -/* Obtain the Invert flag values for each Mapping. */ - inv1 = astGetInvert( mapping1 ); - inv2 = astGetInvert( mapping2 ); - -/* Also determine if these values are explicitly set. */ - set1 = astTestInvert( mapping1 ); - set2 = astTestInvert( mapping2 ); - -/* If both Mappings are actually the same but we need different Invert - flag values to be set, then this can only be achieved by making a - copy. Note if this is necessary. */ - copy = ( ( mapping1 == mapping2 ) && ( invert1 != invert2 ) ); - -/* Clone the first Mapping pointer. Do likewise for the second but - make a copy instead if necessary. */ - map1 = astClone( mapping1 ); - map2 = copy ? astCopy( mapping2 ) : astClone( mapping2 ); - -/* If the Invert value for the first Mapping needs changing, make the - change. */ - if ( invert1 != inv1 ) { - if ( invert1 ) { - astSetInvert( map1, 1 ); - } else { - astClearInvert( map1 ); - } - } - -/* Similarly, change the Invert flag for the second Mapping if - necessary. */ - if ( invert2 != inv2 ) { - if ( invert2 ) { - astSetInvert( map2, 1 ); - } else { - astClearInvert( map2 ); - } - } - -/* Combine the two Mappings into a CmpMap. */ - result = (AstMapping *) astCmpMap( map1, map2, series, "", status ); - -/* If the first Mapping's Invert value was changed, restore it to its - original state. */ - if ( invert1 != inv1 ) { - if ( set1 ) { - astSetInvert( map1, inv1 ); - } else { - astClearInvert( map1 ); - } - } - -/* Similarly, restore the second Mapping's Invert value if - necessary. This step is not needed, however, if a copy was made. */ - if ( ( invert2 != inv2 ) && !copy ) { - if ( set2 ) { - astSetInvert( map2, inv2 ); - } else { - astClearInvert( map2 ); - } - } - -/* Annul the temporary Mapping pointers. */ - map1 = astAnnul( map1 ); - map2 = astAnnul( map2 ); - -/* If an error occurred, then annul the result pointer. */ - if ( !astOK ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -static AstFrameSet *Convert( AstFrame *from, AstFrame *to, - const char *domainlist, int *status ) { -/* -* Name: -* Convert - -* Purpose: -* Determine how to convert between two coordinate systems. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstFrameSet *Convert( AstFrame *from, AstFrame *to, -* const char *domainlist, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the public astConvert -* method inherited fromm the Frame class). - -* Description: -* This function compares two FrameSets and determines whether it -* is possible to convert between the coordinate systems which -* their current Frames represent. If conversion is possible, it -* returns a FrameSet which describes the conversion and which may -* be used (as a Mapping) to transform coordinate values in either -* direction. -* -* If conversion is possible, the Base attributes of both FrameSets -* will be modified on exit to identify the Frames which were used -* as the intermediate coordinate system. - -* Parameters: -* from -* Pointer to a FrameSet whose current Frame represents the -* "source" coordinate system. Note that the Base attribute of -* the FrameSet may be modified by this function. -* to -* Pointer to a FrameSet whose current Frame represents the -* "destination" coordinate system. Note that the Base -* attribute of the FrameSet may be modified by this function. -* domainlist -* Pointer to a null-terminated character string containing a -* comma-separated list of Frame domains. This may be used to -* define a priority order for the different intermediate -* coordinate systems that might be used to perform the -* conversion. -* -* The function will first try to obtain a conversion by making -* use only of intermediate Frames whose Domain attribute -* matches the first domain in this list. If this fails, the -* second domain in the list will be used, and so on, until -* conversion is achieved. A blank domain (e.g. two consecutive -* commas) indicates that all Frames should be considered, -* regardless of their Domain attributes. The list is -* case-insensitive and all white space is ignored. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* If the requested coordinate conversion is possible, the -* function returns a pointer to a FrameSet which describes the -* conversion. Otherwise, a null Object pointer (AST__NULL) is -* returned without error. -* -* If a FrameSet is returned, it will contain two Frames. Frame -* number 1 (its base Frame) will describe the source coordinate -* system, corresponding to the "from" parameter. Frame number 2 -* (its current Frame) will describe the destination coordinate -* system, corresponding to the "to" parameter. The Mapping -* which inter-relates these Frames will perform the required -* conversion between the two coordinate systems. - -* Notes: -* - Either of the "from" and "to" pointers may identify a basic -* Frame instead of a FrameSet, in which case the function behaves -* as if it were a FrameSet containing only a single Frame. -* - 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 is simply a wrap-up for the ConvertX function -* 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 inherited status. */ - if ( !astOK ) return NULL; - -/* Invoke the private "ConvertX" member function with the first two - arguments swapped. */ - return ConvertX( to, from, domainlist, status ); -} - -static AstFrameSet *ConvertX( AstFrame *to, AstFrame *from, - const char *domainlist, int *status ) { -/* -* Name: -* ConvertX - -* Purpose: -* Determine how to convert between two coordinate systems. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstFrameSet *ConvertX( AstFrame *to, AstFrame *from, -* const char *domainlist ) - -* Class Membership: -* FrameSet member function (over-rides the protected "astConvertX" -* method inherited from the Frame class). - -* Description: -* This function performs the processing for the public astConvert -* method (as inherited from the Frame class and over-ridden by the -* FrameSet class) and has exactly the same interface except that -* the order of the first two arguments is swapped. This is a trick -* to allow the astConvert method to be over-ridden by derived -* classes on the basis of the class of either of its first two -* arguments. -* -* See the astConvert method for details of the interface. -*/ - -/* Local Variables: */ - AstFrame *from_frame; /* Pointer to "from" Frame */ - AstFrame *to_frame; /* Pointer to "to" Frame */ - AstFrameSet *cvt; /* Pointer to conversion FrameSet */ - AstFrameSet *result; /* Pointer to FrameSet to be returned */ - 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 individual domain string */ - char *domain_end; /* Pointer to final null of domain string */ - char *domainlist_copy; /* Pointer to copy of domains list */ - int *from_order; /* List of Frame indices in search order */ - int *to_order; /* List of Frame indices in search order */ - int best_score; /* Score from best match */ - int from_base; /* Index of "from" base Frame */ - int from_current; /* Index of "from" current Frame */ - int from_index; /* Index of "from" Frame */ - int from_isframe; /* "from" is a Frame (not a FrameSet)? */ - int from_nframe; /* Number of "from" Frames */ - int from_number; /* Loop counter for "from" Frames */ - int iframe_from; /* Index of best "from" Frame */ - int iframe_to; /* Index of best "to" Frame */ - int match; /* Possible match found? */ - int n; /* Count of Frames */ - int perfect; /* Perfect match found? */ - int score; /* Score from latest match */ - int to_base; /* Index of "to" base Frame */ - int to_current; /* Index of "to" current Frame */ - int to_index; /* Index of "to" Frame */ - int to_isframe; /* "to" is a Frame (not a FrameSet)? */ - int to_nframe; /* Number of "to" Frames */ - int to_number; /* Loop counter for "to" Frames */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Initialise variables to avoid "used of uninitialised variable" - messages from dumb compilers. */ - result_map = NULL; - iframe_from = 0; - iframe_to = 0; - -/* Determine the number of Frames in "from" and the indices of its - base and current Frames. Use values of 1 if "from" is a Frame and - not a FrameSet. */ - from_isframe = !astIsAFrameSet( from ); - from_nframe = from_isframe ? 1 : astGetNframe( from ); - from_base = from_isframe ? 1 : astGetBase( from ); - from_current = from_isframe ? 1 : astGetCurrent( from ); - -/* Obtain similar values for "to". */ - to_isframe = !astIsAFrameSet( to ); - to_nframe = to_isframe ? 1 : astGetNframe( to ); - to_base = to_isframe ? 1 : astGetBase( to ); - to_current = to_isframe ? 1 : astGetCurrent( to ); - -/* Allocate memory for arrays which will hold the indices of "from" - and "to" Frames. */ - from_order = astMalloc( sizeof( int ) * (size_t) from_nframe ); - to_order = astMalloc( sizeof( int ) * (size_t) to_nframe ); - -/* Make a temporary copy of the domains list. */ - domainlist_copy = astStore( NULL, domainlist, - strlen( domainlist ) + (size_t) 1 ); - if ( astOK ) { - -/* Fill the "from_order" array with the indices of all the Frames in - "from", in the order in which they will be used for searching. Use - the base Frame first. */ - n = 0; - from_order[ n++ ] = from_base; - -/* Then add all the "from" Frames in the appropriate order, omitting - the base and current Frames. */ - if ( !astGetInvert( from ) ) { - for ( from_index = 1; from_index <= from_nframe; from_index++ ) { - if ( ( from_index != from_base ) && - ( from_index != from_current ) ) { - from_order[ n++ ] = from_index; - } - } - } else { - for ( from_index = from_nframe; from_index >= 1; from_index-- ) { - if ( ( from_index != from_base ) && - ( from_index != from_current ) ) { - from_order[ n++ ] = from_index; - } - } - } - -/* Finish with the current Frame, if different from the base Frame. */ - if ( from_current != from_base ) from_order[ n++ ] = from_current; - -/* Repeat this process for the "to" Frame. */ - n = 0; - to_order[ n++ ] = to_base; - if ( !astGetInvert( to ) ) { - for ( to_index = 1; to_index <= to_nframe; to_index++ ) { - if ( ( to_index != to_base ) && ( to_index != to_current ) ) { - to_order[ n++ ] = to_index; - } - } - } else { - for ( to_index = to_nframe; to_index >= 1; to_index-- ) { - if ( ( to_index != to_base ) && ( to_index != to_current ) ) { - to_order[ n++ ] = to_index; - } - } - } - if ( to_current != to_base ) to_order[ n++ ] = to_current; - -/* 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. */ - if ( ( domain_end = strchr( domain, ',' ) ) ) *domain_end = '\0'; - -/* 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 through each Frame in "to". Quit looping early if an error - occurs or a perfect match is found. */ - perfect = 0; - for ( to_number = 0; - astOK && !perfect && ( to_number < to_nframe ); - to_number++ ) { - -/* Permute the "to" Frame number into a Frame index to implement the - required search order, and obtain a pointer to the required "to" - Frame. */ - to_index = to_order[ to_number ]; - to_frame = to_isframe ? astClone( to ) : - astGetFrame( to, to_index ); - -/* Loop through each Frame in "from". Quit looping early if an error - occurs or a perfect match is found. */ - for ( from_number = 0; - astOK && !perfect && ( from_number < from_nframe ); - from_number++ ) { - -/* Permute the "from" Frame number into a Frame index to implement the - required search order, and obtain a pointer to the required "from" - Frame. */ - from_index = from_order[ from_number ]; - from_frame = from_isframe ? astClone( from ) : - astGetFrame( from, from_index ); - -/* Attempt to obtain a FrameSet which describes the conversion between - the selected "from" and "to" Frames and test if successful. If so, - we have a potential route to construct the overall Mapping we - want. */ - cvt = astConvert( from_frame, to_frame, domain ); - if ( astOK && cvt ) { - -/* Extract the required Mapping from the returned FrameSet. */ - map = astGetMapping( cvt, AST__BASE, AST__CURRENT ); - -/* If necessary, prefix the Mapping between the "from" current Frame - and the individual "from" Frame we have selected. */ - if ( from_index != from_current ) { - from_map = astGetMapping( from, AST__CURRENT, - from_index ); - tmp = (AstMapping *) astCmpMap( from_map, map, 1, "", status ); - from_map = astAnnul( from_map ); - map = astAnnul( map ); - map = tmp; - } - -/* Similarly, if necessary, append the Mapping between the selected - "to" Frame and the "to" current Frame. */ - if ( to_index != to_current ) { - to_map = astGetMapping( to, to_index, AST__CURRENT ); - tmp = (AstMapping *) astCmpMap( map, to_map, 1, "", status ); - to_map = astAnnul( to_map ); - map = astAnnul( map ); - map = tmp; - } - -/* Simplify the resulting overall Mapping (this is done here because - it may sometimes affect the attribute values used to assign a score - below). */ - tmp = astSimplify( map ); - map = astAnnul( map ); - map = 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 ); - -/* Note which "from" and "to" Frames were used. */ - iframe_from = from_index; - iframe_to = to_index; - } - -/* Annul pointers to the intermediate Objects. */ - map = astAnnul( map ); - cvt = astAnnul( cvt ); - } - from_frame = astAnnul( from_frame ); - } - to_frame = astAnnul( to_frame ); - } - -/* Go on to consider the next field in the domains list. */ - domain = domain_end ? domain_end + 1 : NULL; - } - } - -/* Free the memory allocated for temporary arrays. */ - domainlist_copy = astFree( domainlist_copy ); - from_order = astFree( from_order ); - to_order = astFree( to_order ); - -/* If a result is being returned, then obtain a pointer to the current - "from" Frame and use it to start constructing the result - FrameSet. */ - if ( result_map ) { - from_frame = from_isframe ? astClone( from ) : - astGetFrame( from, AST__CURRENT ); - result = astFrameSet( from_frame, "", status ); - from_frame = astAnnul( from_frame ); - -/* Similarly. obtain a pointer to the current "to" frame and add it to - the result FrameSet (related to the base Frame by the result - Mapping). */ - to_frame = to_isframe ? astClone( to ) : - astGetFrame( to, AST__CURRENT ); - astAddFrame( result, AST__BASE, result_map, to_frame ); - to_frame = astAnnul( to_frame ); - -/* Annul the result Mapping pointer. */ - result_map = astAnnul( result_map ); - } - -/* If successful, and a FrameSet is being returned, then set the base - Frames of "from" and "to" (if they are FrameSets) to indicate the - route used to generate the result Mapping. */ - if ( astOK && result ) { - if ( !from_isframe ) astSetBase( from, iframe_from ); - if ( !to_isframe ) astSetBase( to, iframe_to ); - } - -/* If an error occurred, annul the returned FrameSet pointer. */ - if ( !astOK && result ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -static double Distance( AstFrame *this_frame, - const double point1[], const double point2[], int *status ) { -/* -* Name: -* Distance - -* Purpose: -* Calculate the distance between two points. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* double Distance( AstFrame *this, -* const double point1[], const double point2[], int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astDistance -* method inherited from the Frame class). - -* Description: -* This function finds the distance between two points whose -* FrameSet coordinates are given. The distance calculated is that -* along the geodesic curve that joins the two points. - -* Parameters: -* this -* Pointer to the FrameSet. -* point1 -* An array of double, with one element for each FrameSet axis -* containing the coordinates of the first point. -* point2 -* An array of double, with one element for each FrameSet axis -* containing the coordinates of the second point. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The distance between the two points. - -* Notes: -* - This function will return a "bad" result value (AST__BAD) if -* any of the input coordinates has this value. -* - A "bad" value will also be returned if this function is -* invoked with the AST error status set or if it should fail for -* any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double result; /* Value to return */ - -/* Check the global error status. */ - if ( !astOK ) return AST__BAD; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astDistance method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astDistance( fr, point1, point2 ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = AST__BAD; - -/* Return the result. */ - return result; -} - -static int Equal( AstObject *this_object, AstObject *that_object, int *status ) { -/* -* Name: -* Equal - -* Purpose: -* Test if two FrameSets are equivalent. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int Equal( AstObject *this, AstObject *that, int *status ) - -* Class Membership: -* FrameSet 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 FrameSets are equivalent. - -* Parameters: -* this -* Pointer to the first FrameSet. -* that -* Pointer to the second FrameSet. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* One if the FrameSets are equivalent, zero otherwise. - -* Notes: -* - The two FrameSets are considered equivalent if all the encapsulated -* Frames are equal and all the encapsulated Mappings are equal. -* - 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: */ - AstFrameSet *that; /* Pointer to the second FrameSet structure */ - AstFrameSet *this; /* Pointer to the first FrameSet structure */ - int i; /* Loop index */ - 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 FrameSet structures. */ - this = (AstFrameSet *) this_object; - that = (AstFrameSet *) that_object; - -/* Check the number of nodes and frames are equal. Also check the indices - of the base and current Frames are equal */ - if( this->nframe == that->nframe && - this->nnode == that->nnode && - this->base == that->base && - this->current == that->current ) { - -/* Check the Frames and nodes are equal. */ - result = 1; - for ( i = 0; i < this->nframe; i++ ) { - if( !astEqual( this->frame[ i ], that->frame[ i ] ) || - this->node[ i ] != that->node[ i ] ){ - result = 0; - break; - } - } - -/* Check the Mappings, links and invert flags are equal. */ - if( result ) { - for ( i = 0; i < this->nnode - 1; i++ ) { - if( !astEqual( this->map[ i ], that->map[ i ] ) || - this->link[ i ] != that->link[ i ] || - this->invert[ i ] != that->invert[ i ] ) { - result = 0; - break; - } - } - } - } - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result, */ - return result; -} - -static int Fields( AstFrame *this_frame, 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 FrameSet axis value. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* int astFields( AstFrame *this, int axis, const char *fmt, -* const char *str, int maxfld, char **fields, -* int *nc, double *val ) - -* Class Membership: -* FrameSet member function (over-rides the protected astFields -* method inherited from the Frame class). - -* Description: -* This function identifies the numerical fields within a FrameSet 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 FrameSet. -* axis -* The number of the FrameSet 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: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int result; /* Result field count to return */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis, 1, "astFields" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astFields method to perform the processing. Annul the Frame - pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astFields( fr, axis, fmt, str, maxfld, fields, nc, val ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static AstFrameSet *FindFrame( AstFrame *target_frame, AstFrame *template, - const char *domainlist, int *status ) { -/* -* Name: -* FindFrame - -* Purpose: -* Find a coordinate system with specified characteristics. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstFrameSet *FindFrame( AstFrame *target, AstFrame *template, -* const char *domainlist, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astFindFrame method -* inherited from the Frame class). - -* Description: -* This function uses a "template" Frame to search a 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. - -* Parameters: -* target -* Pointer to the target FrameSet. Note that if a suitable -* coordinate system is found, then the FrameSet's Current -* attribute will be modified to indicate which Frame was used -* to obtain attribute values which were not specified by the -* template. -* template -* Pointer to the template Frame, which should be an instance of -* the type of Frame you wish to find. -* domainlist -* Pointer to a null-terminated character string containing a -* comma-separated list of Frame domains. This may be used to -* establish a priority order for the different types of -* coordinate system that might be found. -* -* The function will first try to find a suitable coordinate -* system whose Domain attribute equals the first domain in this -* list. If this fails, the second domain in the list will be -* used, and so on, until a result is obtained. A blank domain -* (e.g. two consecutive commas) indicates that any coordinate -* system is acceptable (subject to the template) regardless of -* its domain. -* -* This list is case-insensitive and all white space is ignored. -* If you do not wish to restrict the domain in this way, you -* should supply an empty string. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* If the search is successful, the function returns a pointer to a -* FrameSet which contains the Frame found and a description of how -* to convert to (and from) the coordinate system it -* represents. Otherwise, a null Object pointer (AST__NULL) is -* returned without error. -* -* If a FrameSet is returned, it will contain two Frames. Frame -* number 1 (its base Frame) represents the target coordinate -* system and will be the same as the (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. - -* Notes: -* - A null Object pointer (AST__NULL) will be returned if this -* function is invoked with the AST error status set, or if it -* should fail for any reason. -*/ - -/* Local Variables: */ - AstFrame *base_frame; /* Pointer to target base Frame */ - AstFrame *frame; /* Pointer to result Frame */ - AstFrame *selected_frame; /* Pointer to selected target Frame */ - AstFrameSet *found; /* FrameSet pointer (result of search) */ - AstFrameSet *result; /* Pointer to result FrameSet */ - AstFrameSet *target; /* Pointer to target FrameSet structure */ - AstMapping *map; /* Pointer to result Mapping */ - AstMapping *prefix; /* Pointer to prefix Mapping */ - AstMapping *tmp; /* Temporary Mapping pointer */ - char *domain; /* Pointer to individual domain field */ - char *domain_end; /* Pointer to null at end of domain */ - char *domainlist_copy; /* Pointer to copy of domains list */ - int *target_order; /* Array of indices defining search order */ - int match; /* Match obtained? */ - int n; /* Count of target_order elements */ - int target_base; /* Index of target base Frame */ - int target_current; /* Index of target current Frame */ - int target_index; /* Index of selected target Frame */ - int target_nframe; /* Number of Frames in target FrameSet */ - int target_number; /* Loop index for search */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Initialise variables to avoid "used of uninitialised variable" - messages from dumb compilers. */ - target_index = 0; - -/* Obtain a pointer to the target FrameSet structure. */ - target = (AstFrameSet *) target_frame; - -/* Determine the number of Frames in the target FrameSet and the - indices of the current and base Frames. */ - target_nframe = astGetNframe( target ); - target_current = astGetCurrent( target ); - target_base = astGetBase( target ); - -/* Allocate an array to hold a list of all the target Frame indices. */ - target_order = astMalloc( sizeof( int ) * (size_t) target_nframe ); - -/* Make a temporary copy of the domains list. */ - domainlist_copy = astStore( NULL, domainlist, - strlen( domainlist ) + (size_t) 1 ); - if ( astOK ) { - -/* Form a list of the indices of all the Frames in the target in the - order they will be searched for a match. Add the current Frame - index first. */ - n = 0; - target_order[ n++ ] = target_current; - -/* Follow this by the base Frame index, if different. */ - if ( target_base != target_current ) target_order[ n++ ] = target_base; - -/* Then add all the remaining target Frame indices. */ - for ( target_index = 1; target_index <= target_nframe; target_index++ ) { - if ( ( target_index != target_current ) && - ( target_index != target_base ) ) { - target_order[ n++ ] = target_index; - } - } - -/* 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. */ - if ( ( domain_end = strchr( domain, ',' ) ) ) *domain_end = '\0'; - -/* Loop to try and match each target Frame in turn, in the order - identified above. Quit the loop early if an error occurs or a match - is found. */ - for ( target_number = 0; - astOK && !match && ( target_number < target_nframe ); - target_number++ ) { - -/* Permute the target Frame number into a Frame index to implement the - required search order. Then obtain a pointer to the selected target - Frame. */ - target_index = target_order[ target_number ]; - selected_frame = astGetFrame( target, target_index ); - -/* Search the target Frame using the template supplied, together with - the current domain. */ - found = astFindFrame( selected_frame, template, domain ); - -/* Note if a match is found, and extract pointers to the conversion - Mapping and the result Frame from the FrameSet produced. */ - if ( astOK && found ) { - match = 1; - map = astGetMapping( found, AST__BASE, AST__CURRENT ); - frame = astGetFrame( found, AST__CURRENT ); - -/* Obtain a pointer to the Mapping between the target base Frame and - the selected target Frame, and prefix this Mapping to the one - obtained above. */ - prefix = astGetMapping( target, AST__BASE, target_index ); - tmp = (AstMapping *) astCmpMap( prefix, map, 1, "", status ); - prefix = astAnnul( prefix ); - map = astAnnul( map ); - map = tmp; - -/* Simplify the resulting Mapping. */ - tmp = astSimplify( map ); - map = astAnnul( map ); - map = tmp; - -/* Obtain a pointer to the target base Frame, and use this to start - building the result FrameSet. */ - base_frame = astGetFrame( target, AST__BASE ); - result = astFrameSet( base_frame, "", status ); - base_frame = astAnnul( base_frame ); - -/* Add the result Frame, which is related to the base Frame by the - result Mapping. */ - astAddFrame( result, AST__BASE, map, frame ); - -/* Annul pointers to all intermediate Objects. */ - map = astAnnul( map ); - frame = astAnnul( frame ); - found = astAnnul( found ); - } - selected_frame = astAnnul( selected_frame ); - } - -/* Go on to consider the next field in the domains list. */ - domain = domain_end ? domain_end + 1 : NULL; - } - } - -/* Free the temporary arrays. */ - target_order = astFree( target_order ); - domainlist_copy = astFree( domainlist_copy ); - -/* If a result is being returned, set the current Frame of the target - to indicate where the result Frame was found. */ - if ( astOK && result ) astSetCurrent( target, target_index ); - -/* If an error occurred, annul any result FrameSet pointer. */ - if ( !astOK && result ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -static AstPointSet *FrameGrid( AstFrame *this_frame, int size, const double *lbnd, - const double *ubnd, int *status ){ -/* -* Name: -* FrameGrid - -* Purpose: -* Return a grid of points covering a rectangular area of a Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstPointSet *FrameGrid( AstFrame *this_frame, int size, -* const double *lbnd, const double *ubnd, -* int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astFrameGrid -* method inherited from the Frame class). - -* 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: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - AstPointSet *result; /* Value to return */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astFrameGrid method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astFrameGrid( fr, size, lbnd, ubnd ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -static int ForceCopy( AstFrameSet *this, int iframe, int *status ) { -/* -* Name: -* ForceCopy - -* Purpose: -* Force a copy to be made of a Frame, if necessary. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int ForceCopy( AstFrameSet *this, int iframe, int *status ) - -* Class Membership: -* FrameSet member function. - -* Description: -* This function examines a Frame within a FrameSet, identified by its -* Frame index. If the same Frame is found to be referenced a second time -* within the FrameSet, then the original reference is replaced with an -* independent copy of the Frame. -* -* This process supports the preservation of FrameSet integrity in cases -* where the same Frame is referenced more than once. After using this -* function, the nominated Frame's attributes may be modified without -* danger of affecting other parts of the FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. -* iframe -* The index of the Frame to be examined. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* One if a copy of the nominated Frame was made, otherwise zero. - -* Notes: -* - Using this function a second time on the same Frame will have no -* effect, since the first usage will make the Frame independent of any -* other Frames within the FrameSet. -* - 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: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - AstFrame *frame; /* Pointer to Frame */ - AstFrame *tmp; /* Temporary Frame pointer */ - int ifr; /* Loop counter for Frames */ - int result; /* Value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this); - -/* Validate and translate the Frame index supplied. */ - iframe = astValidateFrameIndex( this, iframe, integrity_method ); - -/* If OK, obtain the corresponding Frame pointer (don't clone it). */ - if ( astOK ) { - frame = this->frame[ iframe - 1 ]; - -/* Loop to inspect each Frame in the FrameSet. */ - for ( ifr = 1; ifr <= this->nframe; ifr++ ) { - -/* If the same Frame is referenced anywhere else, then make a copy of it. */ - if ( ( ifr != iframe ) && ( this->frame[ ifr - 1 ] == frame ) ) { - tmp = astCopy( frame ); - -/* If successful, replace the original reference to the Frame with a pointer - to this copy and annul the original pointer. */ - if ( astOK ) { - this->frame[ iframe - 1 ] = tmp; - frame = astAnnul( frame ); - -/* Set the returned result. */ - if ( astOK ) result = 1; - } - -/* Quit looping once a copy has been made. */ - break; - } - } - } - -/* Return the result. */ - return result; -} - -static const char *Format( AstFrame *this_frame, int axis, double value, int *status ) { -/* -* Name: -* Format - -* Purpose: -* Format a coordinate value for a FrameSet axis. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* const char *Format( AstFrame *this, int axis, double value, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astFormat method -* inherited from the Frame class). - -* Description: -* This function returns a pointer to a string containing the -* formatted (character) version of a coordinate value for a -* FrameSet axis. The formatting applied is that specified by a -* previous invocation of the astSetFormat method. A suitable -* default format is applied if necessary. - -* Parameters: -* this -* Pointer to the FrameSet. -* axis -* The number of the axis (zero-based) for which formatting is -* to be performed. -* value -* The coordinate value to be formatted. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A pointer to a null-terminated string containing the formatted -* value. - -* Notes: -* - The returned string pointer may point at memory allocated -* within the FrameSet object, or at static memory. The contents of -* the string may be over-written or the pointer may become invalid -* following a further invocation of the same function or deletion -* of the FrameSet. A copy of the string should therefore be made -* if necessary. -* - A NULL pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - const char *result; /* Pointer value to return */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis, 1, "astFormat" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astFormat method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astFormat( fr, axis, value ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = NULL; - -/* Return the result. */ - return result; -} - -static double Gap( AstFrame *this_frame, int axis, double gap, int *ntick, int *status ) { -/* -* Name: -* Gap - -* Purpose: -* Find a "nice" gap for tabulating FrameSet axis values. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* double Gap( AstFrame *this, int axis, double gap, int *ntick, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astGap method -* inherited from the Frame class). - -* Description: -* This function returns a gap size which produces a nicely spaced -* series of formatted values for a FrameSet 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 FrameSet. -* axis -* The number of the axis (zero-based) for which a gap is to be found. -* gap -* The target gap size. -* ntick -* Address of an int in which to return a convenient number of -* divisions into which the gap can be divided. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The nice gap size. - -* Notes: -* - A value of zero is returned if the target gap size is zero. -* - A negative gap size is returned if the supplied gap size is negative. -* - A value of zero will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double result; /* Gap value to return */ - -/* Check the global error status. */ - if ( !astOK ) return 0.0; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis, 1, "astGap" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astGap method to obtain the required gap value. Annul the - Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astGap( fr, axis, gap, ntick ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = 0.0; - -/* Return the result. */ - return result; -} - -static int GetNode( AstFrameSet *this, int inode, int *nnodes, - int *iframe, AstMapping **map, int *parent, - int *status ) { -/* -*+ -* Name: -* astGetNode - -* Purpose: -* Get information about a single node in a FrameSet tree. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* int astGetNode( AstFrameSet *this, int inode, int *nnodes, -* int *iframe, AstMapping **map, int *parent ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns information about a specified node in a -* FrameSet. It is documented as protected, because it should not -* be used in general purpose software since it depends on the internal -* details of the FrameSet class. However, it is in fact public so that -* it can be used in external software that needs to know about the -* internal structure of a FrameSet (for instance, a graphical FrameSet -* visualisation system). - -* Parameters: -* this -* Pointer to the FrameSet. -* inode -* The zero-based index of the required node. -* nnodes -* Address of an int returned holding the number of nodes defined -* in the FrameSet. -* iframe -* Address of an int returned holding the one-based index of the -* Frame associated with the node. AST__NOFRAME is returned if the -* node has no Frame. -* map -* Address of a Mapping pointer returned holding a pointer to a -* deep copy of the Mapping, if any, from the parent node to the -* requested node. NULL is returned if the node has no parent. -* parent -* Address of an int returned holding the zero-based index of the -* node from which the requested node is derived. -1 is returned if -* the requested node has no parent (i.e. is the root of the tree). - -* Returned Value: -* A non-zero value is returned if the "inode" value is within bounds. -* Otherwise, zero is returned. - -*- -*/ - -/* Local Variables: */ - int jframe; - int result; - -/* Initialise returned values. */ - *nnodes = 0; - *iframe = AST__NOFRAME; - *map = NULL; - *parent = -1; - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Return the number of nodes. */ - *nnodes = this->nnode; - -/* Check the index of the requested node. */ - if( inode >= 0 && inode < this->nnode ) { - -/* Get the index of the Frame - if any - associated with the node. */ - for( jframe = 0; jframe < this->nframe; jframe++ ) { - if( this->node[ jframe ] == inode ) { - *iframe = jframe + 1; - break; - } - } - -/* Get the Mapping - if any - associated with the node. The root node - - node zero - has no mapping or parent node. */ - if( inode > 0 ) { - *map = astCopy( this->map[ inode - 1 ] ); - if( astGetInvert( *map ) != this->invert[ inode - 1 ] ) { - astSetInvert( *map, this->invert[ inode - 1 ] ); - } - -/* The index of the parent node. */ - *parent = this->link[ inode - 1 ]; - } - -/* Indicate success. */ - result = 1; - } - - 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 "frameset.h" -* int GetObjSize( AstObject *this, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astGetObjSize protected -* method inherited from the parent class). - -* Description: -* This function returns the in-memory size of the supplied FrameSet, -* in bytes. - -* Parameters: -* this -* Pointer to the FrameSet. -* 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: */ - AstFrameSet *this; /* Pointer to FrameSet structure */ - int result; /* Result value to return */ - int iframe; /* Loop counter for Frames */ - int inode; /* Loop counter for nodes */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointers to the FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* Invoke the GetObjSize method inherited from the parent class, and then - add on any components of the class structure defined by thsi class - which are stored in dynamically allocated memory. */ - result = (*parent_getobjsize)( this_object, status ); - - for ( iframe = 0; iframe < this->nframe; iframe++ ) { - result += astGetObjSize( this->frame[ iframe ] ); - } - - for ( inode = 0; inode < this->nnode - 1; inode++ ) { - result += astGetObjSize( this->map[ inode ] ); - } - - result += astTSizeOf( this->frame ); - result += astTSizeOf( this->varfrm ); - result += astTSizeOf( this->node ); - result += astTSizeOf( this->map ); - result += astTSizeOf( this->link ); - result += astTSizeOf( this->invert ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result, */ - return result; -} - -static const char *GetAttrib( AstObject *this_object, const char *attrib, int *status ) { -/* -* Name: -* GetAttrib - -* Purpose: -* Get the value of a specified attribute for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* const char *GetAttrib( AstObject *this, const char *attrib, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astGetAttrib -* method inherited from the Frame class). - -* Description: -* This function returns a pointer to the value of a specified -* attribute for a FrameSet, formatted as a character string. - -* Parameters: -* this -* Pointer to the FrameSet. -* attrib -* Pointer to a null-terminated string containing the name of -* the attribute whose value is required. This name should be in -* lower case, with all white space removed. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* - Pointer to a null-terminated string containing the attribute -* value. - -* Notes: -* - The returned string pointer may point at memory allocated -* within the FrameSet, 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 FrameSet. 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 */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - const char *result; /* Pointer value to return */ - int base; /* Base attribute value */ - int current; /* Current attribute value */ - int invert; /* Invert attribute value */ - int nframe; /* Nframe attribute value */ - int nin; /* Nin attribute value */ - int nobject; /* Nobject attribute value */ - int nout; /* Nout attribute value */ - int ref_count; /* RefCount attribute value */ - int report; /* Report attribute value */ - int tranforward; /* TranForward attribute value */ - int traninverse; /* TranInverse attribute value */ - -/* 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 FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* Compare "attrib" with each recognised attribute name in turn, - obtaining the value of the required attribute. If necessary, write - the value into "getattrib_buff" as a null-terminated string in an appropriate - format. Set "result" to point at the result string. */ - -/* We first handle attributes that apply to the FrameSet as a whole - (rather than to the current Frame). */ - -/* AllVariants. */ -/* ------------ */ - if ( !strcmp( attrib, "allvariants" ) ) { - result = astGetAllVariants( this ); - -/* Base. */ -/* ----- */ - } else if ( !strcmp( attrib, "base" ) ) { - base = astGetBase( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", base ); - result = getattrib_buff; - } - -/* Class. */ -/* ------ */ - } else if ( !strcmp( attrib, "class" ) ) { - result = astGetClass( this ); - -/* Current. */ -/* -------- */ - } else if ( !strcmp( attrib, "current" ) ) { - current = astGetCurrent( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", current ); - result = getattrib_buff; - } - -/* ID. */ -/* --- */ - } else if ( !strcmp( attrib, "id" ) ) { - result = astGetID( this ); - -/* Ident. */ -/* ------ */ - } else if ( !strcmp( attrib, "ident" ) ) { - result = astGetIdent( this ); - -/* Invert. */ -/* ------- */ - } else if ( !strcmp( attrib, "invert" ) ) { - invert = astGetInvert( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", invert ); - result = getattrib_buff; - } - -/* Nframe. */ -/* ------- */ - } else if ( !strcmp( attrib, "nframe" ) ) { - nframe = astGetNframe( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", nframe ); - result = getattrib_buff; - } - -/* Nin. */ -/* ---- */ - } else if ( !strcmp( attrib, "nin" ) ) { - nin = astGetNin( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", nin ); - result = getattrib_buff; - } - -/* Nobject. */ -/* -------- */ - } else if ( !strcmp( attrib, "nobject" ) ) { - nobject = astGetNobject( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", nobject ); - result = getattrib_buff; - } - -/* Nout. */ -/* ----- */ - } else if ( !strcmp( attrib, "nout" ) ) { - nout = astGetNout( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", nout ); - result = getattrib_buff; - } - -/* RefCount. */ -/* --------- */ - } else if ( !strcmp( attrib, "refcount" ) ) { - ref_count = astGetRefCount( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", ref_count ); - result = getattrib_buff; - } - -/* Report. */ -/* ------- */ - } else if ( !strcmp( attrib, "report" ) ) { - report = astGetReport( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", report ); - result = getattrib_buff; - } - -/* TranForward. */ -/* ------------ */ - } else if ( !strcmp( attrib, "tranforward" ) ) { - tranforward = astGetTranForward( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", tranforward ); - result = getattrib_buff; - } - -/* TranInverse. */ -/* ------------ */ - } else if ( !strcmp( attrib, "traninverse" ) ) { - traninverse = astGetTranInverse( this ); - if ( astOK ) { - (void) sprintf( getattrib_buff, "%d", traninverse ); - result = getattrib_buff; - } - -/* Variant. */ -/* -------- */ - } else if ( !strcmp( attrib, "variant" ) ) { - result = astGetVariant( this ); - -/* Pass unrecognised attributes on to the FrameSet's current Frame for - further interpretation. */ - } else { - -/* Obtain a pointer to the current Frame and invoke its astGetAttrib - method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astGetAttrib( fr, attrib ); - fr = astAnnul( fr ); - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = NULL; - -/* Return the result. */ - return result; -} - -static AstAxis *GetAxis( AstFrame *this_frame, int axis, int *status ) { -/* -* Name: -* GetAxis - -* Purpose: -* Obtain a pointer to a specified Axis from a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstAxis *GetAxis( AstFrame *this, int axis, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astGetAxis method -* inherited from the Frame class). - -* Description: -* This function returns a pointer to the Axis object associated -* with one of the axes of the current Frame of a FrameSet. This -* object describes the quantity which is represented along that -* axis. - -* Parameters: -* this -* Pointer to the FrameSet. -* axis -* The number of the axis (zero-based) for which an Axis pointer -* is required. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A pointer to the requested Axis object. - -* Notes: -* - The reference count of the requested Axis object will be -* incremented by one to reflect the additional pointer returned by -* this function. -* - A NULL pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstAxis *result; /* Pointer to Axis */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis, 1, "astGetAxis" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astGetAxis method to obtain the required Axis - pointer. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astGetAxis( fr, axis ); - fr = astAnnul( fr ); - -/* If an error occurred, annul the result. */ - if ( !astOK ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -static int GetBase( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astGetBase - -* Purpose: -* Obtain the value of the Base attribute for a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* int astGetBase( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns the value of the Base attribute for a -* FrameSet. This value is an index that identifies the base Frame -* in the FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* The Base attribute value. - -* 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: */ - int invert; /* FrameSet is inverted? */ - int result; /* Value to return */ - -/* Initialise */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Determine if the FrameSet has been inverted. */ - invert = astGetInvert( this ); - -/* If it has not been inverted, return the base Frame index, otherwise - return the index of the current Frame instead. Provide defaults if - necessary. */ - if ( astOK ) { - if ( !invert ) { - result = ( this->base != -INT_MAX ) ? this->base : 1; - } else { - result = ( this->current != -INT_MAX ) ? this->current : - astGetNframe( this ); - } - } - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static int GetCurrent( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astGetCurrent - -* Purpose: -* Obtain the value of the Current attribute for a FrameSet. - -* Type: -* Protected function. - -* Synopsis: -* #include "frameset.h" -* int astGetCurrent( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns the value of the Current attribute for a -* FrameSet. This attribute is an index that identifies the -* current Frame in a FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* Value of the Current attribute. - -* 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: */ - int invert; /* FrameSet is inverted? */ - int result; /* Value to return */ - -/* Initialise */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Determine if the FrameSet has been inverted. */ - invert = astGetInvert( this ); - -/* If it has not been inverted, return the current Frame index, - otherwise return the index of the base Frame instead. Provide - defaults if necessary. */ - if ( astOK ) { - if ( !invert ) { - result = ( this->current != -INT_MAX ) ? this->current : - astGetNframe( this ); - } else { - result = ( this->base != -INT_MAX ) ? this->base : 1; - } - } - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static AstFrame *GetFrame( AstFrameSet *this, int iframe, int *status ) { -/* -*++ -* Name: -c astGetFrame -f AST_GETFRAME - -* Purpose: -* Obtain a pointer to a specified Frame in a FrameSet. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frameset.h" -c AstFrame *astGetFrame( AstFrameSet *this, int iframe ) -f RESULT = AST_GETFRAME( THIS, IFRAME, STATUS ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns a pointer to a specified Frame in a -* FrameSet. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the FrameSet. -c iframe -f IFRAME = INTEGER (Given) -* The index of the required Frame within the FrameSet. This -* value should lie in the range from 1 to the number of Frames -* in the FrameSet (as given by its Nframe attribute). -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astGetFrame() -f AST_GETFRAME = INTEGER -* A pointer to the requested Frame. - -* Notes: -* - A value of AST__BASE or AST__CURRENT may be given for the -c "iframe" parameter to specify the base Frame or the current -f IFRAME argument to specify the base Frame or the current -* Frame respectively. -* - This function increments the RefCount attribute of the -* selected Frame by 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. -*-- -*/ - -/* Local Variables: */ - AstFrame *result; /* Pointer value to return */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Validate and translate the Frame index supplied. */ - iframe = astValidateFrameIndex( this, iframe, "astGetFrame" ); - -/* If OK, clone a pointer to the requested Frame. */ - if ( astOK ) result = astClone( this->frame[ iframe - 1 ] ); - -/* Return the result. */ - return result; -} - -static int GetIsLinear( AstMapping *this_mapping, int *status ){ -/* -* Name: -* GetIsLinear - -* Purpose: -* Return the value of the IsLinear attribute for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "mapping.h" -* void GetIsLinear( AstMapping *this, int *status ) - -* Class Membership: -* FrameSet 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 -* FrameSet, which is the IsLinear value of he base->current Mapping. - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. -*/ -/* Local Variables: */ - AstMapping *map; - int result; - -/* Check global status */ - if( !astOK ) return 0; - -/* Get the Mapping. */ - map = astGetMapping( (AstFrameSet *) this_mapping, AST__BASE, - AST__CURRENT ); - -/* Get its IsLinear attribute value. */ - result = astGetIsLinear( map ); - -/* Free the Mapping. */ - map = astAnnul( map ); - -/* Return the result. */ - return result; -} - -static AstMapping *GetMapping( AstFrameSet *this, int iframe1, int iframe2, int *status ) { -/* -*++ -* Name: -c astGetMapping -f AST_GETMAPPING - -* Purpose: -* Obtain a Mapping that converts between two Frames in a FrameSet. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frameset.h" -c AstMapping *astGetMapping( AstFrameSet *this, int iframe1, int iframe2 ) -f RESULT = AST_GETMAPPING( THIS, IFRAME1, IFRAME2, STATUS ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns a pointer to a Mapping that will convert -* coordinates between the coordinate systems represented by two -* Frames in a FrameSet. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the FrameSet. -c iframe1 -f IFRAME1 = INTEGER (Given) -* The index of the first Frame in the FrameSet. This Frame describes -* the coordinate system for the "input" end of the Mapping. -c iframe2 -f IFRAME2 = INTEGER (Given) -* The index of the second Frame in the FrameSet. This Frame -* describes the coordinate system for the "output" end of the -* Mapping. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Returned Value: -c astGetMapping() -f AST_GETMAPPING = INTEGER -* Pointer to a Mapping whose forward transformation converts -* coordinates from the first coordinate system to the second -* one, and whose inverse transformation converts coordinates in -* the opposite direction. - -* Notes: -* - The returned Mapping will include the clipping effect of any -* Regions which occur on the path between the two supplied -* Frames (this includes the two supplied Frames themselves). -c - The values given for the "iframe1" and "iframe2" parameters -f - The values given for the IFRAME1 and IFRAME2 arguments -* should lie in the range from 1 to the number of Frames in the -* FrameSet (as given by its Nframe attribute). A value of -* AST__BASE or AST__CURRENT may also be given to identify the -* FrameSet's base Frame or current Frame respectively. It is -c permissible for both these parameters to have the same value, in -f permissible for both these arguments to have the same value, in -* which case a unit Mapping (UnitMap) is returned. -* - It should always be possible to generate the Mapping -* requested, but this does necessarily guarantee that it will be -* able to perform the required coordinate conversion. If -* necessary, the TranForward and TranInverse attributes of the -* returned Mapping should be inspected to determine if the -* required transformation is available. -* - A null Object pointer (AST__NULL) will be returned if this -c function is invoked with the AST error status set, or if it -f function is invoked with STATUS set to an error value, or if it -* should fail for any reason. -*-- -*/ - -/* Local Variables: */ - AstFrame *fr; /* Temporary pointer to Frame */ - AstFrame **frames; /* Pointer to array of Frames */ - AstMapping **path; /* Pointer to array of conversion Mappings */ - AstMapping *copy; /* Pointer to copy of Mapping */ - AstMapping *result; /* Result pointer to be returned */ - AstMapping *tmp; /* Temporary pointer for joining Mappings */ - int *forward; /* Pointer to array of Mapping directions */ - int ipath; /* Loop counter for conversion path steps */ - int iframe; /* Frame index */ - int inode; /* Node index */ - int npath; /* Number of steps in conversion path */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Validate and translate the Frame indices supplied. */ - iframe1 = astValidateFrameIndex( this, iframe1, "astGetMapping" ); - iframe2 = astValidateFrameIndex( this, iframe2, "astGetMapping" ); - -/* Allocate memory to hold an array of Mapping pointers and associated - direction flags - a maximum of one element for each Mapping and one - for each Frame in the FrameSet. */ - path = astMalloc( sizeof( AstMapping * ) * (size_t) ( this->nnode - 1 + - this->nframe ) ); - forward = astMalloc( sizeof( int ) * (size_t) ( this->nnode - 1 + - this->nframe ) ); - -/* Allocate memory to hold a list of the Frame pointers (if any) associated - with each node. */ - frames = astMalloc( sizeof( AstFrame * ) * (size_t) ( this->nnode ) ); - -/* If OK, set up an array of Frame pointers indexed by node index. If a - node has no associated Frame store a NULL pointer. This is needed so - that we can find Frame pointers quickly within the Span function. Note, - we simply copy the pointers rather than cloning them, so they do not - need to be annulled when finished with. */ - if ( astOK ) { - for( inode = 0; inode < this->nnode; inode++ ) frames[ inode ] = NULL; - for( iframe = 0; iframe < this->nframe; iframe++ ) { - frames[ this->node[ iframe ] ] = this->frame[ iframe ]; - } - -/* Obtain the Mapping pointers and direction flags needed to convert - coordinates between the nodes associated with the two specified - Frames. */ - npath = Span( this, frames, this->node[ iframe1 - 1 ], - this->node[ iframe2 - 1 ], -1, path, forward, status ) - 1; - -/* If this failed, it indicates a corrupt FrameSet object, so report - an error. */ - if ( npath < 0 ) { - astError( AST__FRSIN, "astGetMapping(%s): Invalid or corrupt " - "%s - could not find conversion path between Frames " - "%d and %d.", status, astGetClass( this ), astGetClass( this ), - iframe1, iframe2 ); - -/* If the conversion path is of zero length (i.e. the two Frames are - the same) then we will return a Mapping which is equivalent to the - Frame. Most classes of Frame are equivalent to a UnitMap. However, - we do not hard-wire this equivalence since some classes of Frame (e.g. - Regions, and CmpFrames containing Regions) do not correspond to a - UnitMap. Instead we use the astIsUnitFrame method on the Frame to determine - if the Frame is equivalent to a UnitMap. If so, create a suitable UnitMap. - If not, return the Frame itself (a form of Mapping). */ - } else if ( npath == 0 ) { - fr = astGetFrame( this, iframe1 ); - if( astIsUnitFrame( fr ) ){ - result = (AstMapping *) astUnitMap( astGetNaxes( fr ), "", status ); - } else { - result = (AstMapping *) astClone( fr ); - } - fr = astAnnul( fr ); - -/* If the conversion path involves at least one non-trivial Mapping, - make a copy of the first Mapping, inverting the copy if - necessary. */ - } else { - result = astCopy( path[ 0 ] ); - if ( !forward[ 0 ] ) astInvert( result ); - -/* Now loop to concatenate any further Mappings. First make a copy of - each additional Mapping and invert the copy if necessary. */ - for ( ipath = 1; ipath < npath; ipath++ ) { - copy = astCopy( path[ ipath ] ); - if ( !forward[ ipath ] ) astInvert( copy ); - -/* Concatenate the copy with the result so far, then annul the pointer - to the copy and save the pointer to the new result. */ - tmp = (AstMapping *) astCmpMap( result, copy, 1, "", status ); - result = astAnnul( result ); - copy = astAnnul( copy ); - result = tmp; - } - } - } - -/* Free the memory allocated for the conversion path information. */ - path = astFree( path ); - forward = astFree( forward ); - frames = astFree( frames ); - -/* If an error occurred, annul the returned Mapping. */ - if ( !astOK ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -static int GetNaxes( AstFrame *this_frame, int *status ) { -/* -* Name: -* GetNaxes - -* Purpose: -* Determine how many axes a FrameSet has. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int GetNaxes( AstFrame *this, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astGetNaxes method -* inherited from the Frame class). - -* Description: -* This function returns the number of axes for a FrameSet. This is equal -* to the number of axes in its current Frame. - -* Parameters: -* this -* Pointer to the FrameSet. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The number of FrameSet axes (zero or more). - -* Notes: -* - A value of zero will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int result; /* Result to be returned */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame. */ - fr = astGetFrame( this, AST__CURRENT ); - -/* Obtain the number of axes in this Frame. */ - result = astGetNaxes( fr ); - -/* Annul the current Frame pointer. */ - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static int GetNframe( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astGetNframe - -* Purpose: -* Determine the number of Frames in a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* int astGetNframe( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns the number of Frames in a FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* The number of Frames in the FrameSet (always 1 or more). - -* 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. -*- -*/ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Return the Frame count. */ - return this->nframe; -} - -static int GetNin( AstMapping *this_mapping, int *status ) { -/* -* Name: -* GetNin - -* Purpose: -* Get the number of input coordinates for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int GetNin( AstMapping *this, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astGetNin method -* inherited from the Frame class). - -* Description: -* This function returns the number of input coordinate values -* required per point by a FrameSet when used to transform a set of -* points (i.e. the number of dimensions of the space in which the -* input points reside). -* -* The value returned is equal to the number of axes in the -* FrameSet's base Frame. - -* Parameters: -* this -* Pointer to the FrameSet. -* 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 *fr; /* Pointer to base Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int result; /* Result to be returned */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_mapping; - -/* Obtain a pointer to the FrameSet's base Frame. */ - fr = astGetFrame( this, AST__BASE ); - -/* Obtain the number of axes in this Frame. */ - result = astGetNaxes( fr ); - -/* Annul the base Frame pointer. */ - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static int GetNout( AstMapping *this_mapping, int *status ) { -/* -* Name: -* GetNout - -* Purpose: -* Get the number of output coordinates for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int GetNout( AstMapping *this, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astGetNout method -* inherited from the Frame class). - -* Description: -* This function returns the number of output coordinate values -* generated per point by a FrameSet when used to transform a set -* of points (i.e. the number of dimensions of the space in which -* the output points reside). -* -* The value returned is equal to the number of axes in the -* FrameSet's current Frame. - -* Parameters: -* this -* Pointer to the FrameSet. -* 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. -*/ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Return the number of axes in the FrameSet's current Frame. */ - return GetNaxes( (AstFrame *) this_mapping, status ); -} - -static const int *GetPerm( AstFrame *this_frame, int *status ) { -/* -* Name: -* GetPerm - -* Purpose: -* Access the axis permutation array for the current Frame of a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* const int *GetPerm( AstFrame *this, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astGetPerm protected -* method inherited from the Frame class). - -* Description: -* This function returns a pointer to the axis permutation array -* for the current Frame of a FrameSet. 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 FrameSet. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Pointer to the current Frame's axis permutation array (a -* constant array of int). Each element of this contains the -* (zero-based) internal axis index to be used in place of the -* external index which is used to address the permutation -* array. If the current Frame has zero axes, this pointer will be -* NULL. - -* Notes: -* - The pointer returned by this function gives direct access to -* data internal to the Frame object. It remains valid only so long -* as the Frame exists. The permutation array contents may be -* modified by other functions which operate on the Frame and this -* may render the returned pointer invalid. -* - A NULL pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to FrameSet structure */ - const int *result; /* Result pointer value */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and then obtain a - pointer to its axis permutation array. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astGetPerm( fr ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = NULL; - -/* Return the result. */ - return result; -} - -static int GetTranForward( AstMapping *this_mapping, int *status ) { -/* -* Name: -* GetTranForward - -* Purpose: -* Determine if a FrameSet defines a forward coordinate transformation. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int GetTranForward( AstMapping *this ) - -* Class Membership: -* Frameset member function (over-rides the astGetTranForward -* protected method inherited from the Frame class). - -* Description: -* This function returns a value indicating whether a FrameSet is -* able to perform a coordinate transformation in the "forward" -* direction. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* Zero if the forward coordinate transformation is not defined, or -* 1 if it is. - -* 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: */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - AstMapping *map; /* Pointer to base->current Mapping */ - int result; /* Result to be returned */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_mapping; - -/* Obtain the Mapping between the base and current Frames in the - FrameSet (note this takes account of whether the FrameSet has been - inverted). */ - map = astGetMapping( this, AST__BASE, AST__CURRENT ); - -/* Determine whether the required transformation is defined. */ - result = astGetTranForward( map ); - -/* Annul the Mapping pointer. */ - map = astAnnul( map ); - -/* If an error occurred, clear the returned result. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static int GetTranInverse( AstMapping *this_mapping, int *status ) { -/* -* Name: -* GetTranInverse - -* Purpose: -* Determine if a FrameSet defines an inverse coordinate transformation. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int GetTranInverse( AstMapping *this ) - -* Class Membership: -* Frameset member function (over-rides the astGetTranInverse -* protected method inherited from the Frame class). - -* Description: -* This function returns a value indicating whether a FrameSet is -* able to perform a coordinate transformation in the "inverse" -* direction. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* Zero if the inverse coordinate transformation is not defined, or -* 1 if it is. - -* 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: */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - AstMapping *map; /* Pointer to base->current Mapping */ - int result; /* Result to be returned */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_mapping; - -/* Obtain the Mapping between the base and current Frames in the - FrameSet (note this takes account of whether the FrameSet has been - inverted). */ - map = astGetMapping( this, AST__BASE, AST__CURRENT ); - -/* Determine whether the required transformation is defined. */ - result = astGetTranInverse( map ); - -/* Annul the Mapping pointer. */ - map = astAnnul( map ); - -/* If an error occurred, clear the returned result. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static int GetUseDefs( AstObject *this_object, int *status ) { -/* -* Name: -* GetUseDefs - -* Purpose: -* Get the value of the UseDefs attribute for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int GetUseDefs( AstObject *this_object, int *status ) { - -* Class Membership: -* FrameSet member function (over-rides the protected astGetUseDefs -* method inherited from the Frame class). - -* Description: -* This function returns the value of the UseDefs attribute for a FrameSet, -* supplying a suitable default. - -* Parameters: -* this -* Pointer to the FrameSet. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* - The USeDefs value. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int result; /* Value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* If the UseDefs value for the FrameSet has been set explicitly, use the - Get method inherited from the parent Frame class to get its value> */ - if( astTestUseDefs( this ) ) { - result = (*parent_getusedefs)( this_object, status ); - -/* Otherwise, supply a default value equal to the UseDefs value of the - current Frame. */ - } else { - fr = astGetFrame( this, AST__CURRENT ); - result = astGetUseDefs( fr ); - fr = astAnnul( fr ); - } - -/* Return the result. */ - return result; -} - -static int GetVarFrm( AstFrameSet *this, int iframe, int *status ) { -/* -* Name: -* GetVarFrm - -* Purpose: -* Get the index of the variants Frame for a nominated Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int GetVarFrm( AstFrameSet *this, int iframe, int *status ) { - -* Class Membership: -* Private function. - -* Description: -* This function returns the index of the variants Frame associated -* with a nominated mirror Frame. See astMirrorVariants. - -* Parameters: -* this -* Pointer to the FrameSet. -* iframe -* The one-based index of the nominated Frame that may potentially be -* a mirror for the variant Mappings in another Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The one-based Frame index of the Frame that defines the variant -* Mappings associated with Frame "iframe". This will be the same as -* "iframe" unless the nominated Frame is a mirror for another Frame. -*/ - -/* Local Variables: */ - int result; /* Value to return */ - -/* Initialise. */ - result = AST__NOFRAME; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Initialise the returned value. */ - result = iframe; - -/* If the nominated Frame is mirroring another Frame, return the index of - the mirrored Frame. Walk up the chain until we reach a Frame which is - not a mirror for another Frame. */ - while( this->varfrm[ result - 1 ] > 0 ) { - if( this->varfrm[ result - 1 ] == result ) { - astError( AST__INTER, "GetVarFrm(FrameSet): FrameSet is corrupt " - "(internal programming error).", status ); - break; - } else { - result = this->varfrm[ result - 1 ]; - } - } - -/* Return the result. */ - return result; -} - -static const char *GetVariant( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astGetVariant - -* Purpose: -* Obtain the value of the Variant attribute for a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* const char *astGetVariant( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns the value of the Variant attribute for a -* FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* The Variant attribute value. - -* Notes: -* - A NULL value will be returned if this function is invoked -* with the global status set, or if it should fail for any reason. -*- -*/ - -/* Local Variables: */ - AstFrame *frm; - AstFrame *vfs; - const char *result; - int icur; - int iuse; - -/* Initialise */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get the one-based index of the current Frame. */ - icur = astGetCurrent( this ); - -/* The current Frame may mirror the variant Mappings in another Frame, - rather than defining any variant Mappings itself. Get the one-based - index of the Frame that defines the variant Mappings to use. */ - iuse = GetVarFrm( this, icur, status ); - -/* Get a pointer to the Variants FrameSet in the used Frame. */ - frm = astGetFrame( this, iuse ); - vfs = astGetFrameVariants( frm ); - -/* If the current Frame has no Variants FrameSet, return the Domain name - of the current Frame. */ - if( !vfs ) { - result = astGetDomain( this ); - -/* Otherwise, return the Domain name of the current Frame in the Variants - FrameSet. Then annul the Variants FrameSet pointer. */ - } else { - result = astGetDomain( vfs ); - vfs = astAnnul( vfs ); - } - -/* Annul the current Frame pointer. */ - frm = astAnnul( frm ); - -/* If an error occurred, clear the result. */ - if ( !astOK ) result = NULL; - -/* Return the result. */ - return result; -} - -void astInitFrameSetVtab_( AstFrameSetVtab *vtab, const char *name, int *status ) { -/* -*+ -* Name: -* astInitFrameSetVtab - -* Purpose: -* Initialise a virtual function table for a FrameSet. - -* Type: -* Protected function. - -* Synopsis: -* #include "frameset.h" -* void astInitFrameSetVtab( AstFrameSetVtab *vtab, const char *name ) - -* Class Membership: -* FrameSet vtab initialiser. - -* Description: -* This function initialises the component of a virtual function -* table which is used by the FrameSet class. - -* Parameters: -* vtab -* Pointer to the virtual function table. The components used by -* all ancestral classes will be initialised if they have not already -* been initialised. -* name -* Pointer to a constant null-terminated character string which contains -* the name of the class to which the virtual function table belongs (it -* is this pointer value that will subsequently be returned by the Object -* astClass function). -*- -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Pointer to thread-specific global data */ - AstFrameVtab *frame; /* Pointer to Frame component of Vtab */ - AstMappingVtab *mapping; /* Pointer to Mapping component of Vtab */ - AstObjectVtab *object; /* Pointer to Object component of Vtab */ - -/* Check the local error status. */ - if ( !astOK ) return; - -/* Get a pointer to the thread specific global data structure. */ - astGET_GLOBALS(NULL); - -/* Initialize the component of the virtual function table used by the - parent class. */ - astInitFrameVtab( (AstFrameVtab *) vtab, name ); - -/* Store a unique "magic" value in the virtual function table. This - will be used (by astIsAFrameSet) to determine if an object belongs - to this class. We can conveniently use the address of the (static) - class_check variable to generate this unique value. */ - vtab->id.check = &class_check; - vtab->id.parent = &(((AstFrameVtab *) vtab)->id); - -/* Initialise member function pointers. */ -/* ------------------------------------ */ -/* Store pointers to the member functions (implemented here) that - provide virtual methods for this class. */ - vtab->AddFrame = AddFrame; - vtab->AddVariant = AddVariant; - vtab->ClearBase = ClearBase; - vtab->ClearCurrent = ClearCurrent; - vtab->GetBase = GetBase; - vtab->GetCurrent = GetCurrent; - vtab->GetFrame = GetFrame; - vtab->GetMapping = GetMapping; - vtab->GetNframe = GetNframe; - vtab->GetNode = GetNode; - vtab->GetAllVariants = GetAllVariants; - vtab->MirrorVariants = MirrorVariants; - vtab->RemapFrame = RemapFrame; - vtab->RemoveFrame = RemoveFrame; - vtab->SetBase = SetBase; - vtab->SetCurrent = SetCurrent; - vtab->TestBase = TestBase; - vtab->TestCurrent = TestCurrent; - vtab->ValidateFrameIndex = ValidateFrameIndex; - - vtab->ClearVariant = ClearVariant; - vtab->GetVariant = GetVariant; - vtab->SetVariant = SetVariant; - vtab->TestVariant = TestVariant; - -/* Save the inherited pointers to methods that will be extended, and - replace them with pointers to the new member functions. */ - object = (AstObjectVtab *) vtab; - - parent_clear = object->Clear; - parent_getobjsize = object->GetObjSize; - object->GetObjSize = GetObjSize; - object->Clear = Clear; - - parent_vset = object->VSet; - object->VSet = VSet; - - parent_getusedefs = object->GetUseDefs; - object->GetUseDefs = GetUseDefs; - -#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; - frame = (AstFrameVtab *) vtab; - - object->ClearAttrib = ClearAttrib; - object->GetAttrib = GetAttrib; - object->SetAttrib = SetAttrib; - object->TestAttrib = TestAttrib; - - object->GetUseDefs = GetUseDefs; - object->Equal = Equal; - object->Cast = Cast; - - mapping->GetIsLinear = GetIsLinear; - mapping->GetNin = GetNin; - mapping->GetNout = GetNout; - mapping->GetTranForward = GetTranForward; - mapping->GetTranInverse = GetTranInverse; - mapping->Rate = Rate; - mapping->ReportPoints = ReportPoints; - mapping->RemoveRegions = RemoveRegions; - mapping->Simplify = Simplify; - mapping->Transform = Transform; - mapping->MapSplit = MapSplit; - - frame->Abbrev = Abbrev; - frame->Angle = Angle; - frame->AxAngle = AxAngle; - frame->AxDistance = AxDistance; - frame->AxNorm = AxNorm; - frame->AxOffset = AxOffset; - frame->CheckPerm = CheckPerm; - frame->ClearDigits = ClearDigits; - frame->ClearDirection = ClearDirection; - frame->ClearDomain = ClearDomain; - frame->ClearFormat = ClearFormat; - frame->ClearLabel = ClearLabel; - frame->ClearMatchEnd = ClearMatchEnd; - frame->ClearMaxAxes = ClearMaxAxes; - frame->ClearMinAxes = ClearMinAxes; - frame->ClearPermute = ClearPermute; - frame->ClearPreserveAxes = ClearPreserveAxes; - frame->ClearSymbol = ClearSymbol; - frame->ClearTitle = ClearTitle; - frame->ClearUnit = ClearUnit; - frame->Convert = Convert; - frame->ConvertX = ConvertX; - frame->Distance = Distance; - frame->Fields = Fields; - frame->FindFrame = FindFrame; - frame->Format = Format; - frame->FrameGrid = FrameGrid; - frame->Centre = Centre; - frame->Gap = Gap; - frame->GetAxis = GetAxis; - frame->GetDigits = GetDigits; - frame->GetDirection = GetDirection; - frame->GetDomain = GetDomain; - frame->GetFormat = GetFormat; - frame->GetLabel = GetLabel; - frame->GetMatchEnd = GetMatchEnd; - frame->GetMaxAxes = GetMaxAxes; - frame->GetMinAxes = GetMinAxes; - frame->GetNaxes = GetNaxes; - frame->GetPerm = GetPerm; - frame->GetPermute = GetPermute; - frame->GetPreserveAxes = GetPreserveAxes; - frame->GetSymbol = GetSymbol; - frame->GetTitle = GetTitle; - frame->GetUnit = GetUnit; - frame->Intersect = Intersect; - frame->IsUnitFrame = IsUnitFrame; - frame->LineContains = LineContains; - frame->LineCrossing = LineCrossing; - frame->LineDef = LineDef; - frame->LineOffset = LineOffset; - frame->Match = Match; - frame->MatchAxes = MatchAxes; - frame->MatchAxesX = MatchAxesX; - frame->Norm = Norm; - frame->NormBox = NormBox; - frame->Offset = Offset; - frame->Offset2 = Offset2; - frame->Overlay = Overlay; - frame->PermAxes = PermAxes; - frame->PickAxes = PickAxes; - frame->PrimaryFrame = PrimaryFrame; - frame->Resolve = Resolve; - frame->ResolvePoints = ResolvePoints; - frame->SetAxis = SetAxis; - frame->SetDigits = SetDigits; - frame->SetDirection = SetDirection; - frame->SetDomain = SetDomain; - frame->SetFormat = SetFormat; - frame->SetLabel = SetLabel; - frame->SetMatchEnd = SetMatchEnd; - frame->SetMaxAxes = SetMaxAxes; - frame->SetMinAxes = SetMinAxes; - frame->SetPermute = SetPermute; - frame->SetPreserveAxes = SetPreserveAxes; - frame->SetSymbol = SetSymbol; - frame->SetTitle = SetTitle; - frame->SetUnit = SetUnit; - frame->SubFrame = SubFrame; - frame->SystemCode = SystemCode; - frame->SystemString = SystemString; - frame->TestDigits = TestDigits; - frame->TestDirection = TestDirection; - frame->TestDomain = TestDomain; - frame->TestFormat = TestFormat; - frame->TestLabel = TestLabel; - frame->TestMatchEnd = TestMatchEnd; - frame->TestMaxAxes = TestMaxAxes; - frame->TestMinAxes = TestMinAxes; - frame->TestPermute = TestPermute; - frame->TestPreserveAxes = TestPreserveAxes; - frame->TestSymbol = TestSymbol; - frame->TestTitle = TestTitle; - frame->TestUnit = TestUnit; - frame->Unformat = Unformat; - frame->ValidateAxis = ValidateAxis; - frame->ValidateAxisSelection = ValidateAxisSelection; - frame->ValidateSystem = ValidateSystem; - - frame->GetActiveUnit = GetActiveUnit; - frame->SetActiveUnit = SetActiveUnit; - frame->TestActiveUnit = TestActiveUnit; - - frame->GetTop = GetTop; - frame->SetTop = SetTop; - frame->TestTop = TestTop; - frame->ClearTop = ClearTop; - - frame->GetBottom = GetBottom; - frame->SetBottom = SetBottom; - frame->TestBottom = TestBottom; - frame->ClearBottom = ClearBottom; - - frame->GetEpoch = GetEpoch; - frame->SetEpoch = SetEpoch; - frame->TestEpoch = TestEpoch; - frame->ClearEpoch = ClearEpoch; - - frame->GetDtai = GetDtai; - frame->SetDtai = SetDtai; - frame->TestDtai = TestDtai; - frame->ClearDtai = ClearDtai; - - frame->GetDut1 = GetDut1; - frame->SetDut1 = SetDut1; - frame->TestDut1 = TestDut1; - frame->ClearDut1 = ClearDut1; - - frame->GetSystem = GetSystem; - frame->SetSystem = SetSystem; - frame->TestSystem = TestSystem; - frame->ClearSystem = ClearSystem; - - frame->GetAlignSystem = GetAlignSystem; - frame->SetAlignSystem = SetAlignSystem; - frame->TestAlignSystem = TestAlignSystem; - frame->ClearAlignSystem = ClearAlignSystem; - - frame->ClearObsLat = ClearObsLat; - frame->TestObsLat = TestObsLat; - frame->GetObsLat = GetObsLat; - frame->SetObsLat = SetObsLat; - - frame->ClearObsAlt = ClearObsAlt; - frame->TestObsAlt = TestObsAlt; - frame->GetObsAlt = GetObsAlt; - frame->SetObsAlt = SetObsAlt; - - frame->ClearObsLon = ClearObsLon; - frame->TestObsLon = TestObsLon; - frame->GetObsLon = GetObsLon; - frame->SetObsLon = SetObsLon; - -/* Declare the copy constructor, destructor and class dump - functions. */ - astSetDelete( vtab, Delete ); - astSetCopy( vtab, Copy ); - astSetDump( vtab, Dump, "FrameSet", - "Set of inter-related coordinate systems" ); - -/* If we have just initialised the vtab for the current class, indicate - that the vtab is now initialised, and store a pointer to the class - identifier in the base "object" level of the vtab. */ - if( vtab == &class_vtab ) { - class_init = 1; - astSetVtabClassIdentifier( vtab, &(vtab->id) ); - } -} - -static void Intersect( AstFrame *this_frame, const double a1[2], - const double a2[2], const double b1[2], - const double b2[2], double cross[2], - int *status ) { -/* -* Name: -* Intersect - -* Purpose: -* Find the point of intersection between two geodesic curves. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void Intersect( AstFrame *this_frame, const double a1[2], -* const double a2[2], const double b1[2], -* const double b2[2], double cross[2], -* int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astIntersect method -* inherited from the Frame class). - -* Description: -* This function finds the coordinate values at the point of -* intersection between two geodesic curves. Each curve is specified -* by two points on the curve. - -* Parameters: -* this -* Pointer to the SkyFrame. -* a1 -* An array of double, with one element for each Frame axis. -* This should contain the coordinates of a point on the first -* geodesic curve. -* a2 -* An array of double, with one element for each Frame axis. -* This should contain the coordinates of a second point on the -* first geodesic curve. -* b1 -* An array of double, with one element for each Frame axis. -* This should contain the coordinates of a point on the second -* geodesic curve. -* b2 -* An array of double, with one element for each Frame axis. -* This should contain the coordinates of a second point on -* the second geodesic curve. -* cross -* An array of double, with one element for each Frame axis -* in which the coordinates of the required intersection -* point will be returned. These will be AST__BAD if the curves do -* not intersect. -* status -* Pointer to the inherited status variable. - -* Notes: -* - The geodesic curve used by this function is the path of -* shortest distance between two points, as defined by the -* astDistance function. -* - This function will return "bad" coordinate values (AST__BAD) -* if any of the input coordinates has this value. -* - For SkyFrames each curve will be a great circle, and in general -* each pair of curves will intersect at two diametrically opposite -* points on the sky. The returned position is the one which is -* closest to point "a1". -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astIntersect method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astIntersect( fr, a1, a2, b1, b2, cross ); - fr = astAnnul( fr ); - -} - -static int IsUnitFrame( AstFrame *this_frame, int *status ){ -/* -* Name: -* IsUnitFrame - -* Purpose: -* Is this Frame equivalent to a UnitMap? - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int IsUnitFrame( AstFrame *this, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astIsUnitFrame -* method inherited from the Frame class). - -* Description: -* This function returns a flag indicating if the supplied Frame is -* equivalent to a UnitMap when treated as a Mapping (note, the Frame -* class inherits from Mapping and therefore every Frame is also a Mapping). - -* Parameters: -* this -* Pointer to the Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A non-zero value is returned if the supplied Frame is equivalent to -* a UnitMap when treated as a Mapping. - -*- -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to FrameSet's current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int result; /* Result to be returned */ - -/* Initialise the returned value. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame. */ - fr = astGetFrame( this, AST__CURRENT ); - -/* Invoke the astIsUnitFrame method for this Frame. */ - result = astIsUnitFrame( fr ); - -/* Annul the Frame pointer. */ - fr = astAnnul( fr ); - -/* If an error occurred, clean up by clearing the returned result. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static int LineContains( AstFrame *this_frame, AstLineDef *l, int def, double *point, int *status ) { -/* -* Name: -* LineContains - -* Purpose: -* Determine if a line contains a point. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int LineContains( AstFrame *this, AstLineDef *l, int def, double *point, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astLineContains -* method inherited from the Frame class). - -* Description: -* This function determines if the supplied point is on the supplied -* line within the supplied Frame. - -* Parameters: -* this -* Pointer to the Frame. -* l -* Pointer to the structure defining the line. -* def -* Should be set non-zero if the "point" array was created by a -* call to astLineCrossing (in which case it may contain extra -* information following the axis values),and zero otherwise. -* point -* Point to an array containing the axis values of the point to be -* tested, possibly followed by extra cached information (see "def"). -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A non-zero value is returned if the line contains the point. - -* Notes: -* - The pointer supplied for "l" should have been created using the -* astLineDef method. These structures contained cached information about -* the lines which improve the efficiency of this method when many -* repeated calls are made. An error will be reported if the structure -* does not refer to the Frame specified by "this". -* - Zero will be returned if this function is invoked with the global -* error status set, or if it should fail for any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - int result; /* Returned value */ - -/* Initialise */ - result =0; - -/* Obtain a pointer to the FrameSet's current Frame and then invoke the - method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( (AstFrameSet *) this_frame, AST__CURRENT ); - result = astLineContains( fr, l, def, point ); - fr = astAnnul( fr ); - -/* Return the result. */ - return result; -} - -static int LineCrossing( AstFrame *this_frame, AstLineDef *l1, AstLineDef *l2, - double **cross, int *status ) { -/* -* Name: -* LineCrossing - -* Purpose: -* Determine if two lines cross. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int LineCrossing( AstFrame *this, AstLineDef *l1, AstLineDef *l2, -* double **cross, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astLineCrossing -* method inherited from the Frame class). - -* Description: -* This function determines if the two suplied line segments cross, -* and if so returns the axis values at the point where they cross. -* A flag is also returned indicating if the crossing point occurs -* within the length of both line segments, or outside one or both of -* the line segments. - -* Parameters: -* this -* Pointer to the Frame. -* l1 -* Pointer to the structure defining the first line. -* l2 -* Pointer to the structure defining the second line. -* cross -* Pointer to a location at which to put a pointer to a dynamically -* alocated array containing the axis values at the crossing. If -* NULL is supplied no such array is returned. Otherwise, the returned -* array should be freed using astFree when no longer needed. If the -* lines are parallel (i.e. do not cross) then AST__BAD is returned for -* all axis values. Note usable axis values are returned even if the -* lines cross outside the segment defined by the start and end points -* of the lines. The order of axes in the returned array will take -* account of the current axis permutation array if appropriate. Note, -* sub-classes such as SkyFrame may append extra values to the end -* of the basic frame axis values. A NULL pointer is returned if an -* error occurs. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A non-zero value is returned if the lines cross at a point which is -* within the [start,end) segment of both lines. If the crossing point -* is outside this segment on either line, or if the lines are parallel, -* zero is returned. Note, the start point is considered to be inside -* the length of the segment, but the end point is outside. - -* Notes: -* - The pointers supplied for "l1" and "l2" should have been created -* using the astLineDef method. These structures contained cached -* information about the lines which improve the efficiency of this method -* when many repeated calls are made. An error will be reported if -* either structure does not refer to the Frame specified by "this". -* - Zero will be returned if this function is invoked with the global -* error status set, or if it should fail for any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - int result; /* Returned value */ - -/* Initialise */ - result =0; - -/* Obtain a pointer to the FrameSet's current Frame and then invoke the - method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( (AstFrameSet *) this_frame, AST__CURRENT ); - result = astLineCrossing( fr, l1, l2, cross ); - fr = astAnnul( fr ); - -/* Return the result. */ - return result; -} - -static AstLineDef *LineDef( AstFrame *this_frame, const double start[2], - const double end[2], int *status ) { -/* -* Name: -* LineDef - -* Purpose: -* Creates a structure describing a line segment in a 2D Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstLineDef *LineDef( AstFrame *this, const double start[2], -* const double end[2], int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astLineDef -* method inherited from the Frame class). - -* Description: -* This function creates a structure containing information describing a -* given line segment within the supplied 2D Frame. This may include -* information which allows other methods such as astLineCrossing to -* function more efficiently. Thus the returned structure acts as a -* cache to store intermediate values used by these other methods. - -* Parameters: -* this -* Pointer to the Frame. Must have 2 axes. -* start -* An array of 2 doubles marking the start of the line segment. -* end -* An array of 2 doubles marking the end of the line segment. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Pointer to the memory structure containing the description of the -* line. This structure should be freed using astFree when no longer -* needed. A NULL pointer is returned (without error) if any of the -* supplied axis values are AST__BAD. - -* Notes: -* - A null pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstLineDef *result; /* Returned value */ - -/* Initialise */ - result = NULL; - -/* Obtain a pointer to the FrameSet's current Frame and then invoke the - method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( (AstFrameSet *) this_frame, AST__CURRENT ); - result = astLineDef( fr, start, end ); - fr = astAnnul( fr ); - -/* Return the result. */ - return result; -} - -static void LineOffset( AstFrame *this_frame, AstLineDef *line, double par, - double prp, double point[2], int *status ){ -/* -* Name: -* LineOffset - -* Purpose: -* Find a position close to a line. - -* Type: -* Private function. - -* Synopsis: -* #include "frame.h" -* void LineOffset( AstFrame *this, AstLineDef *line, double par, -* double prp, double point[2], int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astLineOffset -* method inherited from the Frame class). - -* Description: -* This function returns a position formed by moving a given distance along -* the supplied line, and then a given distance away from the supplied line. - -* Parameters: -* this -* Pointer to the Frame. -* line -* Pointer to the structure defining the line. -* par -* The distance to move along the line from the start towards the end. -* prp -* The distance to move at right angles to the line. Positive -* values result in movement to the left of the line, as seen from -* the observer, when moving from start towards the end. -* status -* Pointer to the inherited status variable. - -* Notes: -* - The pointer supplied for "line" should have been created using the -* astLineDef method. This structure contains cached information about the -* line which improves the efficiency of this method when many repeated -* calls are made. An error will be reported if the structure does not -* refer to the Frame specified by "this". -*/ - - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - -/* Obtain a pointer to the FrameSet's current Frame and then invoke the - method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( (AstFrameSet *) this_frame, AST__CURRENT ); - astLineOffset( fr, line, par, prp, point ); - fr = astAnnul( fr ); -} - -static const char *GetAllVariants( AstFrameSet *this, int *status ) { -/* -* Name: -* GetAllVariants - -* Purpose: -* Get a pointer to a list of the variant Mappings for the current Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* const char *getAllVariants( AstFrameSet *this ) - -* Class Membership: -* FrameSet member function. - -* Description: -* This function returns a space separated list of names for all the -* variant Mappings associated with the current Frame. See attribute -* "Variant". If the current Frame has no variant Mappings, the return -* value contains just the Domain name of the current Frame in the -* supplied FrameSet. - -* Parameters: -* this -* Pointer to the Frame. - -* Returned Value: -* A pointer to a null-terminated string containing the list. - -* Notes: -* - The returned string pointer may point at memory allocated -* within the FrameSet, 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 - AstFrame *frm; - AstFrame *vfrm; - AstFrameSet *vfs; - const char *dom; - const char *result; - int ifrm; - int nc; - int icur; - int nfrm; - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS( this ); - -/* Get the one-based index of the Frame that defines the available - variant Mappings. */ - icur = GetVarFrm( this, astGetCurrent( this ), status ); - -/* Get the variants FrameSet from the Frame selected above. */ - frm = astGetFrame( this, icur ); - vfs = astGetFrameVariants( frm ); - -/* If the Frame does not have a variants FrameSet, just return the DOmain - name from the current Frame. */ - if( !vfs ) { - result = astGetDomain( this ); - -/* If a variants FrameSet was found, form a space sperated list of the - Domain names in the FrameSet, stored in the static "getallvariants_buff" - string. */ - } else if( astOK ){ - nc = 0; - - nfrm = astGetNframe( vfs ); - for( ifrm = 0; ifrm < nfrm; ifrm++ ) { - vfrm = astGetFrame( vfs, ifrm + 1 ); - dom = astGetDomain( vfrm ); - if( astOK ){ - if( ( nc + strlen(dom) + 1 ) < GETALLVARIANTS_BUFF_LEN ) { - nc += sprintf( getallvariants_buff + nc, "%s ", dom ); - } else { - astError( AST__INTER, "astGetAllVariants(%s): Buffer " - "overflow - too many variants.", status, - astGetClass(this) ); - } - } - vfrm = astAnnul( vfrm ); - } - -/* Remove the final space. */ - getallvariants_buff[ nc - 1 ] = 0; - -/* Return a pointer to the buffer. */ - result = getallvariants_buff; - -/* Annul the pointer to the variants FrameSet. */ - vfs = astAnnul( vfs ); - } - -/* Free the pointer to the current Frame. */ - frm = astAnnul( frm ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = NULL; - -/* Return the result. */ - return result; -} - -#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: -* FrameSet 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: */ - AstFrameSet *this; /* Pointer to FrameSet 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 FrameSet structure. */ - this = (AstFrameSet *) 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->nframe; i++ ) { - if( !result ) result = astManageLock( this->frame[ i ], mode, - extra, fail ); - } - - for ( i = 0; i < this->nnode - 1; i++ ) { - if( !result ) result = astManageLock( this->map[ i ], 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 -* FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int *MapSplit( AstMapping *this, int nin, const int *in, AstMapping **map, int *status ) - -* Class Membership: -* FrameSet 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 FrameSet. This is only possible if the specified inputs -* correspond to some subset of the FrameSet outputs. That is, there -* must exist a subset of the FrameSet outputs for which each output -* depends only on the selected FrameSet inputs, and not on any of the -* inputs which have not been selected. If this condition is not met -* by the supplied FrameSet, then a NULL Mapping is returned. - -* Parameters: -* this -* Pointer to the FrameSet to be split (the FrameSet 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 FrameSet, 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 FrameSet 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 FrameSet. 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: */ - AstMapping *bcmap; /* Base->current Mapping */ - int *result; /* Returned pointer */ - -/* Initialise */ - result = NULL; - *map = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get the Mapping from base to current Frame and try to split it. */ - bcmap = astGetMapping( (AstFrameSet *) this_map, AST__BASE, AST__CURRENT ); - result = astMapSplit( bcmap, nin, in, map ); - bcmap = astAnnul( bcmap ); - -/* 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 *this_frame, AstFrame *target, int matchsub, - int **template_axes, int **target_axes, - AstMapping **map, AstFrame **result, int *status ) { -/* -* Name: -* Match - -* Purpose: -* Determine if conversion is possible between two coordinate systems. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int Match( AstFrame *template, AstFrame *target, int matchsub, -* int **template_axes, int **target_axes, -* AstMapping **map, AstFrame **result, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astMatch -* method inherited from the Frame class). - -* Description: -* This function matches the current Frame of a "template" FrameSet -* to a "target" frame and determines whether it is possible to -* convert coordinates between them. If it is, a Mapping that -* performs the transformation is returned along with a new Frame -* that describes the coordinate system that results when this -* Mapping is applied to the current Frame of the target -* FrameSet. 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 FrameSet, whose current Frame -* describes the coordinate system (or set of possible -* coordinate systems) into which we wish to convert our -* coordinates. -* target -* Pointer to the target Frame. This describes the coordinate -* system in which we already have coordinates. -* matchsub -* If zero then a match only occurs if the template is of the same -* class as the target, or of a more specialised class. If non-zero -* then a match can occur even if this is not the case (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 index of the axis in the -* template FrameSet's current Frame from which it is -* derived. If it is not derived from any template FrameSet -* axis, a value of -1 will be returned instead. -* target_axes -* Address of a location where a pointer to int will be returned -* if the requested coordinate conversion is possible. This -* pointer will point at a dynamically allocated array of -* integers with one element for each axis of the "result" Frame -* (see below). It must be freed by the caller (using astFree) -* when no longer required. -* -* For each axis in the result Frame, the corresponding element -* of this array will return the index of the target Frame axis -* from which it is derived. If it is not derived from any -* target Frame axis, a value of -1 will be returned instead. -* map -* Address of a location where a pointer to a new Mapping will -* be returned if the requested coordinate conversion is -* possible. If returned, the forward transformation of this -* Mapping may be used to convert coordinates between the target -* Frame and the result Frame (see below) and the inverse -* transformation will convert in the opposite direction. -* result -* Address of a location where a pointer to a new Frame will be -* returned if the requested coordinate conversion is -* possible. If returned, this Frame describes the coordinate -* system that results from applying the returned Mapping -* (above) to the "target" coordinate system. In general, this -* Frame will combine attributes from (and will therefore be -* more specific than) both the target Frame and the current -* Frame of the template FrameSet. In particular, when the -* template allows the possibility of transformaing to any one -* of a set of alternative coordinate systems, the "result" -* Frame will indicate which of the alternatives was used. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A non-zero value is returned if the requested coordinate -* conversion is possible. Otherwise zero is returned (this will -* not in itself result in an error condition). - -* Notes: -* - A value of zero will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to FrameSet's current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int match; /* Result to be returned */ - -/* Initialise the returned values. */ - *template_axes = NULL; - *target_axes = NULL; - *map = NULL; - *result = NULL; - match = 0; - -/* Check the global error status. */ - if ( !astOK ) return match; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame. */ - fr = astGetFrame( this, AST__CURRENT ); - -/* Invoke the astMatch method for this Frame. */ - match =astMatch( fr, target, matchsub, template_axes, target_axes, - map, result ); - -/* Annul the Frame pointer. */ - fr = astAnnul( fr ); - -/* If an error occurred, clean up by freeing any allocated memory, - annulling returned objects and clearing the returned result. */ - if ( !astOK ) { - *template_axes = astFree( *template_axes ); - *target_axes = astFree( *target_axes ); - *map = astAnnul( *map ); - *result = astAnnul( *result ); - match = 0; - } - -/* Return the result. */ - return match; -} - -static void MatchAxes( AstFrame *frm1_frame, AstFrame *frm2, int *axes, - int *status ) { -/* -* Name: -* MatchAxes - -* Purpose: -* Find any corresponding axes in two Frames. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void MatchAxes( AstFrame *frm1, AstFrame *frm2, int *axes ) -* int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astMatchAxes -* method inherited from the Frame class). - -* Description: -* This function looks for corresponding axes within two supplied -* Frames. An array of integers is returned that contains an element -* for each axis in the second supplied Frame. An element in this array -* will be set to zero if the associated axis within the second Frame -* has no corresponding axis within the first Frame. Otherwise, it -* will be set to the index (a non-zero positive integer) of the -* corresponding axis within the first supplied Frame. - -* Parameters: -* frm1 -* Pointer to the first Frame. -* frm2 -* Pointer to the second Frame. -* axes -* Pointer to an -* integer array in which to return the indices of the axes (within -* the second Frame) that correspond to each axis within the first -* Frame. Axis indices start at 1. A value of zero will be stored -* in the returned array for each axis in the first Frame that has -* no corresponding axis in the second Frame. -* -* The number of elements in this array must be greater than or -* equal to the number of axes in the first Frame. -* status -* Pointer to inherited status value. - -* Notes: -* - Corresponding axes are identified by the fact that a Mapping -* can be found between them using astFindFrame or astConvert. Thus, -* "corresponding axes" are not necessarily identical. For instance, -* SkyFrame axes in two Frames will match even if they describe -* different celestial coordinate systems -*/ - -/* Local Variables: */ - AstFrame *frm1; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get a pointer to the current Frame in the FrameSet. */ - frm1 = astGetFrame( (AstFrameSet *) frm1_frame, AST__CURRENT ); - -/* Invoke the astMatchAxesX on the second Frame. */ - astMatchAxesX( frm2, frm1, axes ); - -/* Free resources */ - frm1 = astAnnul( frm1 ); -} - -static void MatchAxesX( AstFrame *frm2_frame, AstFrame *frm1, int *axes, - int *status ) { -/* -* Name: -* MatchAxesX - -* Purpose: -* Find any corresponding axes in two Frames. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void MatchAxesX( AstFrame *frm2, AstFrame *frm1, int *axes ) -* int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astMatchAxesX -* method inherited from the Frame class). - -* This function looks for corresponding axes within two supplied -* Frames. An array of integers is returned that contains an element -* for each axis in the second supplied Frame. An element in this array -* will be set to zero if the associated axis within the second Frame -* has no corresponding axis within the first Frame. Otherwise, it -* will be set to the index (a non-zero positive integer) of the -* corresponding axis within the first supplied Frame. - -* Parameters: -* frm2 -* Pointer to the second Frame. -* frm1 -* Pointer to the first Frame. -* axes -* Pointer to an integer array in which to return the indices of -* the axes (within the first Frame) that correspond to each axis -* within the second Frame. Axis indices start at 1. A value of zero -* will be stored in the returned array for each axis in the second -* Frame that has no corresponding axis in the first Frame. -* -* The number of elements in this array must be greater than or -* equal to the number of axes in the second Frame. -* status -* Pointer to inherited status value. - -* Notes: -* - Corresponding axes are identified by the fact that a Mapping -* can be found between them using astFindFrame or astConvert. Thus, -* "corresponding axes" are not necessarily identical. For instance, -* SkyFrame axes in two Frames will match even if they describe -* different celestial coordinate systems -*/ - -/* Local Variables: */ - AstFrame *frm2; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get a pointer to the current Frame in the FrameSet. */ - frm2 = astGetFrame( (AstFrameSet *) frm2_frame, AST__CURRENT ); - -/* Invoke the astMatchAxesX on the current Frame. */ - astMatchAxesX( frm2, frm1, axes ); - -/* Free resources */ - frm2 = astAnnul( frm2 ); -} - -static void MirrorVariants( AstFrameSet *this, int iframe, int *status ) { -/* -*++ -* Name: -c astMirrorVariants -f AST_MIRRORVARIANTS - -* Purpose: -* Make the current Frame mirror the variant Mappings in another Frame. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frameset.h" -c void astMirrorVariants( AstFrameSet *this, int iframe ) -f CALL AST_MIRRORVARIANTS( THIS, IFRAME, STATUS ) - -* Class Membership: -* FrameSet method. - -* Description: -c This function -f This routine -* indicates that all access to the Variant attribute of the current -* Frame should should be forwarded to some other nominated Frame in -* the FrameSet. For instance, if a value is set subsequently for the -* Variant attribute of the current Frame, the current Frame will be left -* unchanged and the setting is instead applied to the nominated Frame. -* Likewise, if the value of the Variant attribute is requested, the -* value returned is the value stored for the nominated Frame rather -* than the current Frame itself. -* -* This provides a mechanism for propagating the effects of variant -* Mappings around a FrameSet. If a new Frame is added to a FrameSet -* by connecting it to an pre-existing Frame that has two or more variant -* Mappings, then it may be appropriate to set the new Frame so that it -* mirrors the variants Mappings of the pre-existing Frame. If this is -* done, then it will be possible to select a specific variant Mapping -* using either the pre-existing Frame or the new Frame. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the FrameSet. -c iframe -f IFRAME = INTEGER (Given) -* The index of the Frame within the FrameSet which is to be -* mirrored by the current Frame. This value should lie in the range -* from 1 to the number of Frames in the FrameSet (as given by its -* Nframe attribute). If AST__NOFRAME is supplied (or the current -* Frame is specified), then any mirroring established by a previous -* call to this -c function -f routine -* is disabled. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -* - Mirrors can be chained. That is, if Frame B is set to be a mirror -* of Frame A, and Frame C is set to be a mirror of Frame B, then -* Frame C will act as a mirror of Frame A. -* - Variant Mappings cannot be added to the current Frame if it is -* mirroring another Frame. So calls to the -c astAddVariant function -f AST_ADDVARIANT routine -* will cause an error to be reported if the current Frame is -* mirroring another Frame. -* - A value of AST__BASE may be given for the -c "iframe" parameter -f IFRAME argument -* to specify the base Frame. -* - Any variant Mappings explicitly added to the current Frame using -c astAddVariant -f AST_ADDVARIANT -* will be ignored if the current Frame is mirroring another Frame. - -*-- -*/ - -/* Local Variables: */ - int icur; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get the current Frame index. */ - icur = astGetCurrent( this ); - -/* If AST__NOFRAME, disable any mirroring. */ - if( iframe == AST__NOFRAME ) { - this->varfrm[ icur - 1 ] = 0; - -/* Otherwise, validate and translate the Frame index supplied. */ - } else { - iframe = astValidateFrameIndex( this, iframe, "astMirrorVariants" ); - -/* If the current Frame has been specified, disable any mirroring. */ - if( iframe == icur ) { - this->varfrm[ icur - 1 ] = 0; - -/* Otherwise, store the one-based variants frame index. */ - } else { - this->varfrm[ icur - 1 ] = iframe; - } - } -} - -static void Norm( AstFrame *this_frame, double value[], int *status ) { -/* -* Name: -* Norm - -* Purpose: -* Normalise a set of FrameSet coordinates. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void Norm( AstAxis *this, double value[], int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astNorm method -* inherited from the Frame class). - -* Description: -* This function converts a set of coordinate values for the -* current Frame of a FrameSet, which might potentially be -* unsuitable for display to a user (for instance, may lie outside -* the expected range of values) into a set of acceptable -* alternative values suitable for display. -* -* Typically, for Frames whose axes represent cyclic values (such -* as angles or positions on the sky), this function wraps an -* arbitrary set of coordinates, so that they lie within the first -* cycle (say zero to 2*pi or -pi/2 to +pi/2). For Frames with -* ordinary linear axes, without constraints, this function will -* typically return the original coordinate values unchanged. - -* Parameters: -* this -* Pointer to the FrameSet. -* value -* An array of double, with one element for each FrameSet axis. -* This should contain the initial set of coordinate values, -* which will be modified in place. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to the current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astNorm method to obtain the new values. Annul the Frame - pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astNorm( fr, value ); - fr = astAnnul( fr ); -} - -static void NormBox( AstFrame *this_frame, double lbnd[], double ubnd[], - AstMapping *reg, int *status ) { -/* -* Name: -* NormBox - -* Purpose: -* Extend a box to include effect of any singularities in the Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void astNormBox( AstFrame *this, double lbnd[], double ubnd[], -* AstMapping *reg, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astNormBox method inherited -* from the Frame class). - -* Description: -* This function modifies a supplied box to include the effect of any -* singularities in the co-ordinate system represented by the Frame. -* For a normal Cartesian coordinate system, the box will be returned -* unchanged. Other classes of Frame may do other things. For instance, -* a SkyFrame will check to see if the box contains either the north -* or south pole and extend the box appropriately. - -* Parameters: -* this -* Pointer to the Frame. -* lbnd -* An array of double, with one element for each Frame axis -* (Naxes attribute). Initially, this should contain a set of -* lower axis bounds for the box. They will be modified on exit -* to include the effect of any singularities within the box. -* ubnd -* An array of double, with one element for each Frame axis -* (Naxes attribute). Initially, this should contain a set of -* upper axis bounds for the box. They will be modified on exit -* to include the effect of any singularities within the box. -* reg -* A Mapping which should be used to test if any singular points are -* inside or outside the box. The Mapping should leave an input -* position unchanged if the point is inside the box, and should -* set all bad if the point is outside the box. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to the current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astNormBox method to obtain the new values. Annul the Frame - pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astNormBox( fr, lbnd, ubnd, reg ); - fr = astAnnul( fr ); -} - -static void Offset( AstFrame *this_frame, const double point1[], - const double point2[], double offset, double point3[], int *status ) { -/* -* Name: -* Offset - -* Purpose: -* Calculate an offset along a geodesic curve. - -* Type: -* Public virtual function. - -* Synopsis: -* #include "frameset.h" -* void Offset( AstFrame *this, -* const double point1[], const double point2[], -* double offset, double point3[], int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astOffset -* method inherited from the Frame class). - -* Description: -* This function finds the FrameSet coordinate values of a point -* which is offset a specified distance along the geodesic curve -* between two other points. - -* Parameters: -* this -* Pointer to the FrameSet. -* point1 -* An array of double, with one element for each FrameSet axis. -* This should contain the coordinates of the point marking the -* start of the geodesic curve. -* point2 -* An array of double, with one element for each FrameSet axis -* This should contain the coordinates of the point marking the -* end of the geodesic curve. -* offset -* The required offset from the first point along the geodesic -* curve. If this is positive, it will be towards the second -* point. If it is negative, it will be in the opposite -* direction. This offset need not imply a position lying -* between the two points given, as the curve will be -* extrapolated if necessary. -* point3 -* An array of double, with one element for each FrameSet axis -* in which the coordinates of the required point will be -* returned. -* status -* Pointer to the inherited status variable. - -* Notes: -* - The geodesic curve used by this function is the path of -* shortest distance between two points, as defined by the -* astDistance function. -* - This function will return "bad" coordinate values (AST__BAD) -* if any of the input coordinates has this value. -* - "Bad" coordinate values will also be returned if the two -* points supplied are coincident (or otherwise fail to uniquely -* specify a geodesic curve) but the requested offset is non-zero. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astOffset method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astOffset( fr, point1, point2, offset, point3 ); - fr = astAnnul( fr ); -} - -static double Offset2( AstFrame *this_frame, const double point1[2], - double angle, double offset, double point2[2], int *status ){ -/* -* Name: -* Offset2 - -* Purpose: -* Calculate an offset along a geodesic curve in a 2D Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* double Offset2( AstFrame *this, const double point1[2], double angle, -* double offset, double point2[2], int *status ); - -* Class Membership: -* FrameSet member function (over-rides the protected astOffset2 -* method inherited from the Frame class). - -* Description: -* This function finds the Frame coordinate values of a point which -* is offset a specified distance along the geodesic curve at a -* given angle from a specified starting point. It can only be -* used with 2-dimensional Frames. -* -* For example, in a basic Frame, this offset will be along the -* straight line joining two points. For a more specialised Frame -* describing a sky coordinate system, however, it would be along -* the great circle passing through two sky positions. - -* Parameters: -* this -* Pointer to the Frame. -* point1 -* An array of double, with one element for each Frame axis -* (Naxes attribute). This should contain the coordinates of the -* point marking the start of the geodesic curve. -* angle -* The angle (in radians) from the positive direction of the second -* axis, to the direction of the required position, as seen from -* the starting position. Positive rotation is in the sense of -* rotation from the positive direction of axis 2 to the positive -* direction of axis 1. -* offset -* The required offset from the first point along the geodesic -* curve. If this is positive, it will be in the direction of the -* given angle. If it is negative, it will be in the opposite -* direction. -* point2 -* An array of double, with one element for each Frame axis -* in which the coordinates of the required point will be returned. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The direction of the geodesic curve at the end point. That is, the -* angle (in radians) between the positive direction of the second -* axis and the continuation of the geodesic curve at the requested -* end point. Positive rotation is in the sense of rotation from -* the positive direction of axis 2 to the positive direction of axis 1. - -* Notes: -* - The geodesic curve used by this function is the path of -* shortest distance between two points, as defined by the -* astDistance function. -* - An error will be reported if the Frame is not 2-dimensional. -* - This function will return "bad" coordinate values (AST__BAD) -* if any of the input coordinates has this value. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double result; /* Value to return */ - -/* Check the global error status. */ - if ( !astOK ) return AST__BAD; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astOffset2 method for this Frame. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astOffset2( fr, point1, angle, offset, point2 ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = AST__BAD; - -/* Return the result. */ - return result; -} - -static void Overlay( AstFrame *template_frame, const int *template_axes, - AstFrame *result, int *status ) { -/* -* Name: -* Overlay - -* Purpose: -* Overlay the attributes of a template FrameSet on to another Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void Overlay( AstFrame *template, const int *template_axes, -* AstFrame *result, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astOverlay -* method inherited from the Frame class). - -* Description: -* This function overlays attributes from the current Frame of a -* FrameSet 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 FrameSet, for whose current Frame -* values should have been explicitly set for any attribute -* which is to be transferred. -* template_axes -* Pointer to an array of int, with one element for each axis of -* the "result" Frame (see below). For each axis in the result -* frame, the corresponding element of this array should contain -* the (zero-based) index of the axis in the current Frame of -* the template FrameSet to which it corresponds. This array is -* used to establish from which template Frame axis any -* axis-dependent attributes should be obtained. -* -* If any axis in the result Frame is not associated with a -* template Frame axis, the corresponding element of this array -* should be set to -1. -* -* If a NULL pointer is supplied, the template and result axis -* indices are assumed to be identical. -* result -* Pointer to the Frame which is to receive the new attribute values. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *template; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - template = (AstFrameSet *) template_frame; - -/* Obtain a pointer to the current Frame and invoke its astOverlay - method to overlay its attributes. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( template, AST__CURRENT ); - astOverlay( fr, template_axes, result ); - fr = astAnnul( fr ); -} - -static void PermAxes( AstFrame *this_frame, const int perm[], int *status ) { -/* -* Name: -* PermAxes - -* Purpose: -* Permute the order of a FrameSet's axes. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void PermAxes( AstFrame *this, const int perm[], int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astPermAxes method -* inherited from the Frame class). - -* Description: -* This function permutes the order in which the axes in the -* current Frame of a FrameSet occur. - -* Parameters: -* this -* Pointer to the FrameSet. -* perm -* An array of int (with one element for each axis of the -* FrameSet's current Frame) which lists the axes in their new -* order. Each element of this array should be a (zero-based) -* axis index identifying the axes according to their old -* (un-permuted) order. -* status -* Pointer to the inherited status variable. - -* Notes: -* - Only genuine permutations of the axis order are permitted, so -* each axis must be referenced exactly once in the "perm" array. -* - If more than one axis permutation is applied to the same Frame -* in a FrameSet, the effects are cumulative. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - AstPermMap *map; /* Pointer to axis permutation Mapping */ - int *invperm; /* Pointer to inverse permutation array */ - int axis; /* Loop counter for axes */ - int naxes; /* Number of FrameSet axes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the permutation array, to check that it describes a - genuine permutation. */ - astCheckPerm( this, perm, "astPermAxes" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astPermAxes method to permute its axes. Annul the Frame - pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astPermAxes( fr, perm ); - fr = astAnnul( fr ); - -/* Obtain the number of axes in the FrameSet's current Frame and allocate - memory to hold an inverse permutation array. */ - naxes = astGetNaxes( this ); - invperm = astMalloc( sizeof( int ) * (size_t) naxes ); - -/* Fill the inverse permutation array with values that will invert the - axis permutation supplied. */ - if ( astOK ) { - for ( axis = 0; axis < naxes; axis++ ) invperm[ perm[ axis ] ] = axis; - -/* Create a PermMap that will permute coordinate values in the same way as - the current Frame's axes have been permuted. */ - map = astPermMap( naxes, invperm, naxes, perm, NULL, "", status ); - -/* Modify the Frame's relationship to the rest of the Frames in the - FrameSet so that the correct coordinate values remain associated - with the permuted axes. */ - astRemapFrame( this, AST__CURRENT, map ); - -/* Annul the PermMap and free the inverse permutation array. */ - map = astAnnul( map ); - } - invperm = astFree( invperm ); -} - -static AstFrame *PickAxes( AstFrame *this_frame, int naxes, const int axes[], - AstMapping **map, int *status ) { -/* -* Name: -* PickAxes - -* Purpose: -* Create a new Frame by picking axes from a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstFrame *PickAxes( AstFrame *this, int naxes, const int axes[], -* AstMapping **map, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astPickAxes protected -* method inherited from the Frame class). - -* Description: -* This function creates a new Frame whose axes are copies of axes -* picked from the current Frame of an existing FrameSet. Other -* Frame attributes are also copied from this current Frame to the -* new Frame. Zero or more of the original axes may be picked in -* any order, but each can be used only once. Additional axes (with -* default characteristics) may be included in the new Frame if -* required. -* -* Optionally, a Mapping that converts between the original Frame's -* axes and those of the new Frame may also be returned. - -* Parameters: -* this -* Pointer to the FrameSet. -* naxes -* The number of axes required in the new Frame. -* axes -* Pointer to an array of int with naxes elements. This should -* contain (zero based) axis indices specifying the axes which -* are to be included in the new Frame, in the order -* required. Each axis index may occur only once. -* -* If additional (default) axes are also to be included, the -* corresponding elements of this array should be set to -1. -* map -* Address of a location to receive a pointer to a new -* Mapping. This will be a PermMap (or a UnitMap as a special -* case) that describes the axis permutation that has taken -* place between the current Frame of the FrameSet and the new -* Frame. The forward transformation will convert from the -* original FrameSet's axes to the new one's, and vice versa. -* -* If this Mapping is not required, a NULL value may be supplied -* for this parameter. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Pointer to the new Frame. - -* Notes: -* - The class of object returned may differ from that of the -* original current Frame, depending on which axes are -* selected. For example, if a single axis is picked from a -* SkyFrame (which always has two axes), the resulting Frame cannot -* be a valid SkyFrame, so will revert to the parent class (Frame) -* instead. -* - The new Frame contains a deep copy of all the data selected -* from the original current Frame. Modifying the new Frame will -* therefore not affect the FrameSet or the Frames it contains. -* - A NULL pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrame *frame; /* Pointer to Frame to be returned */ - AstFrameSet *this; /* Pointer to FrameSet structure */ - -/* Initialise the returned pointers. */ - if ( map ) *map = NULL; - frame = NULL; - -/* Check the global error status. */ - if ( !astOK ) return frame; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Check that a valid set of axes is being selected . */ - astValidateAxisSelection( this, naxes, axes, "astPickAxes" ); - -/* Obtain a pointer to the FrameSet's current Frame and use its - astPickAxes method to obtain the required new Frame and - Mapping. Annul the current Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - frame = astPickAxes( fr, naxes, axes, map ); - fr = astAnnul( fr ); - -/* If an error occurred, annul the Mapping pointer (if requested) and - the new Frame pointer. */ - if ( !astOK ) { - if ( map ) *map = astAnnul( *map ); - frame = astAnnul( frame ); - } - -/* Return the pointer to the new Frame. */ - return frame; -} - -static void PrimaryFrame( AstFrame *this_frame, int axis1, - AstFrame **frame, int *axis2, int *status ) { -/* -* Name: -* PrimaryFrame - -* Purpose: -* Uniquely identify a primary Frame and one of its axes. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void PrimaryFrame( AstFrame *this, int axis1, AstFrame **frame, -* int *axis2, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected -* astPrimaryFrame method inherited from the Frame class). - -* Description: -* This function returns information about the underlying (primary) -* Frame corresponding to a specified axis of the current Frame of -* a FrameSet, when this current Frame may be a compound Frame -* composed of more than one simpler one. - -* Parameters: -* this -* Pointer to the FrameSet. -* axis1 -* An axis index (zero-based) identifying the axis of the -* FrameSet's current Frame 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 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). -* status -* Pointer to the inherited status variable. - -* 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. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Initialise the returned values. */ - *frame = NULL; - *axis2 = 0; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index supplied. */ - (void) astValidateAxis( this, axis1, 1, "astPrimaryFrame" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke its - astPrimaryFrame method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astPrimaryFrame( fr, axis1, frame, axis2 ); - fr = astAnnul( fr ); - -/* If an error occurred, annul the returned object and clear the - returned axis value. */ - if ( !astOK ) { - *frame = astAnnul( *frame ); - *axis2 = 0; - } -} - -static double Rate( AstMapping *this_mapping, double *at, int ax1, int ax2, int *status ){ -/* -* Name: -* Rate - -* Purpose: -* Calculate the rate of change of a Mapping output. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* result = Rate( AstMapping *this, double *at, int ax1, int ax2, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astRate method -* inherited from the Frame class). - -* This function evaluates the rate of change of a specified output of -* the supplied Mapping with respect to a specified input, at a -* specified input position. -* -* The result is estimated by interpolating the function using a -* fourth order polynomial in the neighbourhood of the specified -* position. The size of the neighbourhood used is chosen to minimise -* the RMS residual per unit length between the interpolating -* polynomial and the supplied Mapping function. - -* Parameters: -* this -* Pointer to the Mapping to be applied. -* at -* The address of an array holding the axis values at the position -* at which the rate of change is to be evaluated. The number of -* elements in this array should equal the number of inputs to the -* Mapping. -* ax1 -* The index of the Mapping output for which the rate of change is to -* be found (output numbering starts at 0 for the first output). -* ax2 -* The index of the Mapping input which is to be varied in order to -* find the rate of change (input numbering starts at 0 for the first -* input). -* status -* Pointer to the inherited status variable. - -* Returned Value: -* astRate() -* The rate of change of Mapping output "ax1" with respect to input -* "ax2", evaluated at "at", or AST__BAD if the value cannot be -* calculated. - -* Notes: -* - A value of AST__BAD will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*- -*/ - -/* Local Variables: */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - AstMapping *map; /* Pointer to the base->current Mapping */ - double result; /* Returned rate of change */ - -/* Check the global error status. */ - if ( !astOK ) return AST__BAD; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_mapping; - -/* Obtain the Mapping between the base and current Frames in the - FrameSet (note this takes account of whether the FrameSet has been - inverted). */ - map = astGetMapping( this, AST__BASE, AST__CURRENT ); - -/* Invoke the astRate method on the Mapping. */ - result = astRate( map, at, ax1, ax2 ); - -/* Annul the Mapping pointer. */ - map = astAnnul( map ); - -/* Return a pointer to the output PointSet. */ - return result; -} - -static void RecordIntegrity( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* RecordIntegrity - -* Purpose: -* Record the current integrity state of a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void RecordIntegrity( AstFrameSet *this, int *status ) - -* Class Membership: -* FrameSet member function. - -* Description: -* This function makes a record of the current integrity state of a -* FrameSet by taking a copy of its current Frame (it stores a -* pointer to this copy in a static variable). If the current Frame -* is subsequently modified, the RestoreIntegrity function can then -* attempt to restore the FrameSet's integrity to this recorded -* state by appropriately remapping its current Frame. - -* Parameters: -* this -* Pointer to the FrameSet. -*- -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - AstFrame *current; /* Pointer to current Frame */ - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this); - -/* Initialise the record of the FrameSet's integrity. */ - integrity_frame = NULL; - integrity_lost = 0; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet's current Frame. */ - current = astGetFrame( this, AST__CURRENT ); - -/* Make a copy of this Frame, storing its pointer. */ - integrity_frame = astCopy( current ); - -/* Annul the current Frame pointer. */ - current = astAnnul( current ); -} - -static void RemapFrame( AstFrameSet *this, int iframe, AstMapping *map, int *status ) { -/* -*++ -* Name: -c astRemapFrame -f AST_REMAPFRAME - -* Purpose: -* Modify a Frame's relationship to other Frames in a FrameSet. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frameset.h" -c void astRemapFrame( AstFrameSet *this, int iframe, AstMapping *map ) -f CALL AST_REMAPFRAME( THIS, IFRAME, MAP, STATUS ) - -* Class Membership: -* FrameSet method. - -* Description: -c This function modifies the relationship (i.e. Mapping) between a -f This routine modifies the relationship (i.e. Mapping) between a -* specified Frame in a FrameSet and the other Frames in that -* FrameSet. -* -* Typically, this might be required if the FrameSet has been used -* to calibrate (say) an image, and that image is re-binned. The -* Frame describing the image will then have undergone a coordinate -* transformation, and this should be communicated to the associated -c FrameSet using this function. -f FrameSet using this routine. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the FrameSet. -c iframe -f IFRAME = INTEGER (Given) -* The index within the FrameSet of the Frame to be modified. -* This value should lie in the range from 1 to the number of -* Frames in the FrameSet (as given by its Nframe attribute). -c map -f MAP = INTEGER (Given) -* Pointer to a Mapping whose forward transformation converts -* coordinate values from the original coordinate system -* described by the Frame to the new one, and whose inverse -* transformation converts in the opposite direction. -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -* - A value of AST__BASE or AST__CURRENT may be given for the -c "iframe" parameter to specify the base Frame or the current -f IFRAME argument to specify the base Frame or the current -* Frame respectively. -* - The relationship between the selected Frame and any other -c Frame within the FrameSet will be modified by this function, -f Frame within the FrameSet will be modified by this routine, -* but the relationship between all other Frames in the FrameSet -* remains unchanged. -* - The number of input coordinate values accepted by the Mapping -* (its Nin attribute) and the number of output coordinate values -* generated (its Nout attribute) must be equal and must match the -* number of axes in the Frame being modified. -* - If a simple change of axis order is required, then the -c astPermAxes function may provide a more straightforward method -f AST_PERMAXES routine may provide a more straightforward method -* of making the required changes to the FrameSet. -c - This function cannot be used to change the number of Frame -f - This routine cannot be used to change the number of Frame -* axes. To achieve this, a new Frame must be added to the FrameSet -c (astAddFrame) and the original one removed if necessary -c (astRemoveFrame). -f (AST_ADDFRAME) and the original one removed if necessary -f (AST_REMOVEFRAME). -* - Any variant Mappings associated with the remapped Frame (except -* for the current variant) will be lost as a consequence of calling this -* method (see attribute "Variant"). -*-- -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to Frame */ - int icur; /* Index of original current Frame */ - int naxes; /* Number of Frame axes */ - int nin; /* Number of Mapping input coordinates */ - int nout; /* Number of Mapping output coordinates */ - int varfrm; /* The index of the variants frame */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Validate and translate the Frame index supplied. */ - iframe = astValidateFrameIndex( this, iframe, "astRemapFrame" ); - -/* Variant Mappings from a source node to a destination node are stored - within the Frame object associated with the destination node. But - remapping a Frame causes the Frame to be dissociated from its original - node, and associated with a new node, leaving the original node - without any Frame in which to store its variant mappings. So we are - forced to remove the variant Mappings if the Frame is remapped. We do - this by clearing the Variant attribute before the Frame is remapped. - This will leave the current variant as the sole Mapping between the - original source and destination nodes. However, if the Frame being - remapped is just a mirror for another Frame, then we do not need to - do this since the Frame being mirrored is not itself being remapped - and so can retain its variant mappings. So we temporarily prevent the - remapped Frame from acting as a mirror before we clear the Variant - attribute. */ - icur = astGetCurrent( this ); - astSetCurrent( this, iframe ); - - varfrm = this->varfrm[ iframe - 1 ]; - this->varfrm[ iframe - 1 ] = 0; - - astClearVariant( this ); - - this->varfrm[ iframe - 1 ] = varfrm; - astSetCurrent( this, icur ); - -/* Obtain the number of input and output coordinates per point for the - Mapping supplied. */ - nin = astGetNin( map ); - nout = astGetNout( map ); - -/* Obtain a pointer to the specified Frame and determine how many axes - it has. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, iframe ); - naxes = astGetNaxes( fr ); - fr = astAnnul( fr ); - -/* Check that the number of input coordinates matches the number of - Frame axes and report an error if necessary. */ - if ( astOK ) { - if ( nin != naxes ) { - astError( AST__NCPIN, "astRemapFrame(%s): Bad number of %s input " - "coordinate values (%d).", status, astGetClass( this ), - astGetClass( map ), nin ); - astError( AST__NCPIN, "The %s given should accept %d coordinate " - "value%s for each input point.", status, astGetClass( map ), naxes, - ( naxes == 1 ) ? "" : "s" ); - -/* Similarly, check that the number of output coordinates matches the - number of Frame axes. */ - } else if ( nout != naxes ) { - astError( AST__NCPIN, "astRemapFrame(%s): Bad number of %s output " - "coordinate values (%d).", status, astGetClass( this ), - astGetClass( map ), nout ); - astError( AST__NCPIN, "The %s given should generate %d " - "coordinate value%s for each output point.", status, - astGetClass( map ), naxes, ( naxes == 1 ) ? "" : "s" ); - } - } - -/* If there is more than one Frame present in the FrameSet, extend the - FrameSet arrays to hold a new node. */ - if ( astOK && ( this->nframe > 1 ) ) { - this->map = astGrow( this->map, this->nnode, sizeof( AstMapping * ) ); - this->link = astGrow( this->link, this->nnode, sizeof( int ) ); - this->invert = astGrow( this->invert, this->nnode, sizeof( int ) ); - -/* Clone and store a pointer to the Mapping. */ - if ( astOK ) { - this->map[ this->nnode - 1 ] = astClone( map ); - -/* Add a new "link" element showing that the new node is derived from - that of the old Frame and store the current value of the Invert - attribute for the Mapping. */ - this->link[ this->nnode - 1 ] = this->node[ iframe - 1 ]; - this->invert[ this->nnode - 1 ] = astGetInvert( map ); - -/* Increment the node count and associate the modified Frame with the - new node. */ - if ( astOK ) { - this->nnode++; - this->node[ iframe - 1 ] = this->nnode - 1; - -/* Tidy the resulting set of nodes, because the node originally - referenced by the Frame may no longer be needed. This also - simplifies any compound Mapping which may result if this node is - removed. */ - TidyNodes( this, status ); - } - } - } -} - -static void RemoveFrame( AstFrameSet *this, int iframe, int *status ) { -/* -*++ -* Name: -c astRemoveFrame -f AST_REMOVEFRAME - -* Purpose: -* Remove a Frame from a FrameSet. - -* Type: -* Public virtual function. - -* Synopsis: -c #include "frameset.h" -c void astRemoveFrame( AstFrameSet *this, int iframe ) -f CALL AST_REMOVEFRAME( THIS, IFRAME, STATUS ) - -* Class Membership: -* FrameSet method. - -* Description: -c This function removes a Frame from a FrameSet. All other Frames -f This routine removes a Frame from a FrameSet. All other Frames -* in the FrameSet have their indices re-numbered from one (if -* necessary), but are otherwise unchanged. - -* Parameters: -c this -f THIS = INTEGER (Given) -* Pointer to the FrameSet. -c iframe -f IFRAME = INTEGER (Given) -* The index within the FrameSet of the Frame to be removed. -* This value should lie in the range from 1 to the number of -* Frames in the FrameSet (as given by its Nframe attribute). -f STATUS = INTEGER (Given and Returned) -f The global status. - -* Notes: -* - Removing a Frame from a FrameSet does not affect the -* relationship between other Frames in the FrameSet, even if they -* originally depended on the Frame being removed. -* - The number of Frames in a FrameSet cannot be reduced to zero. -* An error will result if an attempt is made to remove the only -* remaining Frame. -* - A value of AST__BASE or AST__CURRENT may be given for the -c "iframe" parameter to specify the base Frame or the current -f IFRAME argument to specify the base Frame or the current -* Frame respectively. -* - If a FrameSet's base or current Frame is removed, the Base or -* Current attribute (respectively) of the FrameSet will have its -* value cleared, so that another Frame will then assume its role -* by default. -* - If any other Frame is removed, the base and current Frames -* will remain the same. To ensure this, the Base and/or Current -* attributes of the FrameSet will be changed, if necessary, to -* reflect any change in the indices of these Frames. -*-- -*/ - -/* Local Variables: */ - int ifr; /* Loop counter for Frames */ - int ii; /* Base/current Frame index */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Validate and translate the Frame index supplied. */ - iframe = astValidateFrameIndex( this, iframe, "astRemoveFrame" ); - if ( astOK ) { - -/* Reject any attempt to remove the final Frame from the FrameSet. */ - if ( this->nframe == 1 ) { - astError( AST__REMIN, "astRemoveFrame(%s): Invalid attempt to " - "remove the only Frame in a %s.", status, astGetClass( this ), - astGetClass( this ) ); - -/* If OK, annul the pointer to the selected Frame. */ - } else { - this->frame[ iframe - 1 ] = astAnnul( this->frame[ iframe - 1 ] ); - -/* Ensure that the variant Mappings in the Frame being removed are not - mirrored by any other Frames in the FrameSet. */ - RemoveMirrors( this, iframe, status ); - -/* Any Frames that are mirroring variants in Frames higher than the - removed Frame need to have their mirror frame indices decremented. */ - for ( ifr = 1; ifr <= this->nframe; ifr++ ) { - if( this->varfrm[ ifr - 1 ] > iframe ) this->varfrm[ ifr - 1 ]--; - } - -/* Loop to move all subsequent Frame pointers down in the FrameSet's - "frame" array to close the resulting gap. Also move the associated - "node" and "varfrm" array contents in the same way. */ - for ( ifr = iframe; ifr < this->nframe; ifr++ ) { - this->frame[ ifr - 1 ] = this->frame[ ifr ]; - this->node[ ifr - 1 ] = this->node[ ifr ]; - this->varfrm[ ifr - 1 ] = this->varfrm[ ifr ]; - } - this->frame[ this->nframe - 1 ] = NULL; - this->node[ this->nframe - 1 ] = -1; - this->varfrm[ this->nframe - 1 ] = 0; - -/* Decrement the Frame count. */ - this->nframe--; - -/* Tidy the nodes in the FrameSet. */ - TidyNodes( this, status ); - -/* If the Base attribute is set and the removed Frame was the base - Frame, then clear the attribute value so that a new base Frame will - be selected by default. */ - if ( astTestBase( this ) ) { - ii = astGetBase( this ); - if ( iframe == ii ) { - astClearBase( this ); - -/* If the index of the removed Frame is smaller than the base Frame - index, then decrement the Base attribute so that the same base - Frame will be used in future. */ - } else if ( iframe < ii ) { - astSetBase( this, ii - 1 ); - } - } - -/* Repeat the above procedure for the current Frame. */ - if ( astTestCurrent( this ) ) { - ii = astGetCurrent( this ); - if ( iframe == ii ) { - astClearCurrent( this ); - } else if ( iframe < ii ) { - astSetCurrent( this, ii - 1 ); - } - } - } - } -} - -static void RemoveMirrors( AstFrameSet *this, int iframe, int *status ) { -/* -* Name: -* RemoveMirrors - -* Purpose: -* Ensure no other Frames act as mirrors for a specified Frame. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void RemoveMirrors( AstFrameSet *this, int iframe, int *status ) - -* Class Membership: -* Private function. - -* Description: -* This function searchs the FrameSet for Frames that are currently -* acting as mirrors for the variant Mappings in the Frame with index -* "iframe", and disables mirroring in any found Frames. It should be -* used when "iframe" has its variant Mappings removed. - -* Parameters: -* this -* Pointer to the FrameSet. -* iframe -* One-based index of a Frame that has had its variant Mappings -* removed. -* status -* Pointer to the inherited status variable. - -*/ - -/* Local Variables: */ - int *frmlist; - int ifr; - int nfrm; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Iniitalise a list to hold the indices of the FRames that mirror - "iframe". */ - nfrm = 0; - frmlist = NULL; - -/* Check each Frame in the FrameSet. */ - for( ifr = 1; ifr <= this->nframe; ifr++ ) { - -/* Get the index of the Frame that defines the variant Mappings to use - with Frame "ifr". If this is "iframe", then add "ifr" to the list of - Frames that need to be "de-mirrored". We cannot "de-mirror" the Frame - immediately as doing so may break a chain of mirrors, resulting in the - Frames higher up the chain no longer being associated with "iframe". */ - if( GetVarFrm( this, ifr, status ) == iframe ) { - frmlist = astGrow( frmlist, nfrm + 1, sizeof( *frmlist ) ); - if( astOK ) frmlist[ nfrm++ ] = ifr; - } - } - -/* Loop round all the Frames found above that mirror "iframe". */ - for( ifr = 0; ifr < nfrm; ifr++ ) { - -/* Indicate that the Frame no longer mirrors any other Frame. */ - this->varfrm[ frmlist[ ifr ] - 1 ] = 0; - } - -/* Free the list. */ - frmlist = astFree( frmlist ); -} - -static AstMapping *RemoveRegions( AstMapping *this_mapping, int *status ) { -/* -* Name: -* RemoveRegions - -* Purpose: -* Remove any Regions from a Mapping. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstMapping *RemoveRegions( AstMapping *this, int *status ) - -* Class Membership: -* FrameSet method (over-rides the astRemoveRegions method inherited -* from the Mapping class). - -* Description: -* This function searches the supplied Mapping (which may be a -* compound Mapping such as a FrameSet) for any component Mappings -* that are instances of the AST Region class. It then creates a new -* Mapping from which all Regions have been removed. If a Region -* cannot simply be removed (for instance, if it is a component of a -* parallel FrameSet), then it is replaced with an equivalent UnitMap -* in the returned Mapping. -* -* The implementation provided by the FrameSet class invokes the -* astRemoveRegions method on all the component Frames and Mappings, -* and joins the results together into a new FrameSet. - -* Parameters: -* this -* Pointer to the original Region. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A pointer to the modified mapping. - -* Notes: -* - A NULL pointer value will be returned if this function is -* invoked with the AST error status set, or if it should fail for -* any reason. -*/ - -/* Local Variables: */ - AstFrame **newfrms; /* Array of new Frames */ - AstFrameSet *new; /* Pointer to new FrameSet */ - AstFrameSet *this; /* Pointer to FrameSet structure */ - AstMapping **newmaps; /* Array of new Mappings */ - AstMapping *result; /* Result pointer to return */ - int changed; /* Has any mapping been changed? */ - int i; /* Loop count */ - int nax; /* Number of Frame axes */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get a pointer to the FrameSet. */ - this = (AstFrameSet *) this_mapping; - -/* Allocate arrays to hold the modified Mapping and Frame pointers. */ - newmaps = astMalloc( sizeof( AstMapping *)*( this->nnode - 1 ) ); - newfrms = astMalloc( sizeof( AstFrame *)*( this->nframe ) ); - if( astOK ) { - -/* Invoke the astRemoveRegions method on all the component Mappings. */ - changed = 0; - for( i = 0; i < this->nnode - 1; i++ ) { - newmaps[ i ] = astRemoveRegions( this->map[ i ] ); - -/* Note if any Mapping was changed. */ - if( newmaps[ i ] != this->map[ i ] ) { - changed = 1; - -/* The implementation of the astRemoveRegions method provided by the - Region class returns a Frame rather than a UnitMap. But we need - Mappings here, not Frames. So if the new Mapping is a Frame, replace - it with an equivalent UnitMap. */ - if( astIsAFrame( newmaps[ i ] ) ) { - nax = astGetNin( newmaps[ i ] ); - (void) astAnnul( newmaps[ i ] ); - newmaps[ i ] = (AstMapping *) astUnitMap( nax, " ", status ); - } - } - } - -/* Invoke the astRemoveRegions method on all the component Frames. */ - for( i = 0; i < this->nframe; i++ ) { - newfrms[ i ] = astRemoveRegions( this->frame[ i ] ); - -/* Note if any Frame was changed. */ - if( newfrms[ i ] != this->frame[ i ] ) changed = 1; - } - -/* If no component was modified, just return a clone of the supplied - pointer. */ - if( ! changed ) { - result = astClone( this ); - -/* Otherwise, we need to create a new FrameSet to return. We take a deep - copy of the supplied FrameSet and then modify the Mappings and Frames - so that we retain any extra information in the supplied FrameSet. */ - } else { - new = astCopy( this ); - - for( i = 0; i < this->nnode - 1; i++ ) { - (void) astAnnul( new->map[ i ] ); - new->map[ i ] = astClone( newmaps[ i ] ); - } - - for( i = 0; i < this->nframe; i++ ) { - (void) astAnnul( new->frame[ i ] ); - new->frame[ i ] = astClone( newfrms[ i ] ); - } - - result = (AstMapping *) new; - } - -/* Free resources. */ - for( i = 0; i < this->nnode - 1; i++ ) { - newmaps[ i ] = astAnnul( newmaps[ i ] ); - } - - for( i = 0; i < this->nframe; i++ ) { - newfrms[ i ] = astAnnul( newfrms[ i ] ); - } - - } - - newfrms = astFree( newfrms ); - newmaps = astFree( newmaps ); - -/* Annul the returned Mapping if an error has occurred. */ - if( !astOK ) result = astAnnul( result ); - -/* 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 FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "mapping.h" -* void ReportPoints( AstMapping *this, int forward, -* AstPointSet *in_points, AstPointSet *out_points, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astReportPoints -* method inherited from the Frame class). - -* Description: -* This function reports the coordinates of a set of points before -* and after being transformed by a FrameSet, by writing them to -* standard output. - -* Parameters: -* this -* Pointer to the FrameSet. -* forward -* A non-zero value indicates that the FrameSet'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 FrameSet was -* applied. -* out_points -* Pointer to a PointSet which is associated with the -* coordinates of the same set of points after the FrameSet has -* been applied. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - AstFrame *base_frame; /* Pointer to current Frame */ - AstFrame *current_frame; /* Pointer to base Frame */ - AstFrameSet *this; /* Pointer to the FrameSet 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 FrameSet structure. */ - this = (AstFrameSet *) 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; - -/* Obtain pointers to the FrameSet's base and current Frames. */ - base_frame = astGetFrame( this, AST__BASE ); - current_frame = astGetFrame( this, AST__CURRENT ); - -/* Loop to report the effect of the transformation on each point in - turn. */ - if ( astOK ) { - for ( point = 0; point < npoint; point++ ) { - -/* Report the input coordinates (in parentheses and separated by - commas). Format each value for display using the appropriate - Frame's astFormat method. */ - printf( "(" ); - for ( coord = 0; coord < ncoord_in; coord++ ) { - printf( "%s%s", coord ? ", " : "", - astFormat( forward ? base_frame : current_frame, - coord, ptr_in[ coord ][ point ] ) ); - } - -/* Similarly report the output coordinates, this time formatting - values using the other Frame's astFormat method. */ - printf( ") --> (" ); - for ( coord = 0; coord < ncoord_out; coord++ ) { - printf( "%s%s", coord ? ", " : "", - astFormat( forward ? current_frame : base_frame, - coord, ptr_out[ coord ][ point ] ) ); - } - printf( ")\n" ); - } - } - -/* Annul the Frame pointers. */ - base_frame = astAnnul( base_frame ); - current_frame = astAnnul( current_frame ); -} - -static void Resolve( AstFrame *this_frame, const double point1[], - const double point2[], const double point3[], - double point4[], double *d1, double *d2, int *status ){ -/* -* Name: -* Resolve - -* Purpose: -* Resolve a vector into two orthogonal components - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void Resolve( AstFrame *this, const double point1[], -* const double point2[], const double point3[], -* double point4[], double *d1, double *d2, int *status ); - -* Class Membership: -* FrameSet member function (over-rides the protected astResolve -* method inherited from the Frame class). - -* Description: -* This function resolves a vector into two perpendicular components. -* The vector from point 1 to point 2 is used as the basis vector. -* The vector from point 1 to point 3 is resolved into components -* parallel and perpendicular to this basis vector. The lengths of the -* two components are returned, together with the position of closest -* aproach of the basis vector to point 3. - -* Parameters: -* this -* Pointer to the Frame. -* point1 -* An array of double, with one element for each Frame axis -* (Naxes attribute). This marks the start of the basis vector, -* and of the vector to be resolved. -* point2 -* An array of double, with one element for each Frame axis -* (Naxes attribute). This marks the end of the basis vector. -* point3 -* An array of double, with one element for each Frame axis -* (Naxes attribute). This marks the end of the vector to be -* resolved. -* point4 -* An array of double, with one element for each Frame axis -* in which the coordinates of the point of closest approach of the -* basis vector to point 3 will be returned. -* d1 -* The address of a location at which to return the distance from -* point 1 to point 4 (that is, the length of the component parallel -* to the basis vector). Positive values are in the same sense as -* movement from point 1 to point 2. -* d2 -* The address of a location at which to return the distance from -* point 4 to point 3 (that is, the length of the component -* perpendicular to the basis vector). The value is always positive. -* status -* Pointer to the inherited status variable. - -* Notes: -* - Each vector used in this function is the path of -* shortest distance between two points, as defined by the -* astDistance function. -* - This function will return "bad" coordinate values (AST__BAD) -* if any of the input coordinates has this value, or if the required -* output values are undefined. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astResolve method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astResolve( fr, point1, point2, point3, point4, d1, d2 ); - fr = astAnnul( fr ); - -} - -static AstPointSet *ResolvePoints( AstFrame *this_frame, const double point1[], - const double point2[], AstPointSet *in, - AstPointSet *out, int *status ) { -/* -* Name: -* ResolvePoints - -* Purpose: -* Resolve a set of vectors into orthogonal components - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstPointSet *astResolvePoints( AstFrame *this, const double point1[], -* const double point2[], AstPointSet *in, -* AstPointSet *out ) - -* Class Membership: -* FrameSet member function (over-rides the astResolvePoints method -* inherited from the Frame class). - -* Description: -* This function takes a Frame and a set of vectors encapsulated -* in a PointSet, and resolves each one into two orthogonal components, -* returning these two components in another PointSet. -* -* This is exactly the same as the public astResolve method, except -* that this method allows many vectors to be processed in a single call, -* thus reducing the computational cost of overheads of many -* individual calls to astResolve. - -* Parameters: -* this -* Pointer to the Frame. -* point1 -* An array of double, with one element for each Frame axis -* (Naxes attribute). This marks the start of the basis vector, -* and of the vectors to be resolved. -* point2 -* An array of double, with one element for each Frame axis -* (Naxes attribute). This marks the end of the basis vector. -* in -* Pointer to the PointSet holding the ends of the vectors to be -* resolved. -* out -* Pointer to a PointSet which will hold the length of the two -* resolved components. A NULL value may also be given, in which -* case a new PointSet will be created by this function. - -* Returned Value: -* Pointer to the output (possibly new) PointSet. The first axis will -* hold the lengths of the vector components parallel to the basis vector. -* These values will be signed (positive values are in the same sense as -* movement from point 1 to point 2. The second axis will hold the lengths -* of the vector components perpendicular to the basis vector. These -* values will always be positive. - -* Notes: -* - The number of coordinate values per point in the input -* PointSet must match the number of axes in the supplied Frame. -* - If an output PointSet is supplied, it must have space for -* sufficient number of points and 2 coordinate values per point. -* - A null pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstPointSet *result; /* Pointer to output PointSet */ - AstFrameSet *this; /* Pointer to FrameSet structure */ - AstFrame *fr; /* Pointer to current Frame */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astResolvePoints method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astResolvePoints( this, point1, point2, in, out ); - fr = astAnnul( fr ); - -/* Return a pointer to the output PointSet. */ - return result; - -} - -static void RestoreIntegrity( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* RestoreIntegrity - -* Purpose: -* Restore a previous integrity state for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void RestoreIntegrity( AstFrameSet *this ) - -* Class Membership: -* FrameSet member function. - -* Description: -* This function restores a FrameSet to a previous integrity state, -* as recorded (in static variables) by a previous invocation of -* the RecordIntegrity function. It does this by appropriately -* remapping the FrameSet's current Frame, if this appears -* necessary. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Notes: -* - The previous record of the FrameSet's integrity state (as -* recorded by RecordIntegrity) is deleted by this function, even -* if it is invoked with the global error status set. -* - An error will result if the previous integrity state cannot be -* restored. -*- -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - AstFrame *current; /* Pointer to current Frame */ - AstFrameSet *cvt; /* Pointer to conversion FrameSet */ - AstMapping *map; /* Pointer to conversion Mapping */ - int flags; /* Flags associated with current frame */ - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this); - -/* Check that a previous record of the FrameSet's integrity state has - been made. Do not modify the FrameSet if it appears that the - previous integrity state has not been lost (i.e. that the current - Frame has not been modified), nor if there is only one Frame - present. Check the global error status. */ - if ( integrity_frame && integrity_lost && ( astGetNframe( this ) > 1 ) && - astOK ) { - -/* Obtain a pointer to the current Frame. */ - current = astGetFrame( this, AST__CURRENT ); - -/* Since we need to obtain a conversion between the recorded copy of - this Frame and the current one, we must match their Domain - attributes (otherwise conversion cannot be performed). Do this by - changing the recorded copy as necessary. */ - if ( astTestDomain( current ) ) { - astSetDomain( integrity_frame, astGetDomain( current ) ); - } else { - astClearDomain( integrity_frame ); - } - -/* Temporarily set both Frames AST__INTFLAG flag to indicate that the - following call to astConvert is part of the process of restoring a - FrameSet's integrity. Some classes of Frame (e.g. DSBSpecFrames) may - choose to return a different Mapping in this case. */ - astSetFrameFlags( integrity_frame, astGetFrameFlags( integrity_frame ) - | AST__INTFLAG ); - flags = astGetFrameFlags( current ); - astSetFrameFlags( current, flags | AST__INTFLAG ); - -/* Obtain the required conversion FrameSet, restore the original frame - flags and annul the current Frame pointer. */ - cvt = astConvert( integrity_frame, current, "" ); - astSetFrameFlags( current, flags ); - current = astAnnul( current ); - -/* If no conversion could be found, then the FrameSet's integrity - state cannot be restored, so report an error. */ - if ( !cvt ) { - if( astOK ) { - astError( AST__ILOST, "%s(%s): Cannot maintain %s integrity.", status, - integrity_method, astGetClass( this ), - astGetClass( this ) ); - } - -/* Otherwise, obtain a pointer to the conversion Mapping. */ - } else { - map = astGetMapping( cvt, AST__BASE, AST__CURRENT ); - -/* If the Mapping is not a UnitMap (i.e. a null Mapping), then use it - to remap the FrameSet's current Frame. */ - if ( strcmp( astGetClass( map ), "UnitMap" ) ) { - astRemapFrame( this, AST__CURRENT, map ); - } - -/* Annul the conversion Mapping and Frameset pointers. */ - map = astAnnul( map ); - cvt = astAnnul( cvt ); - } - } - -/* Delete the recorded integrity information by annulling the original - copy of the current Frame (thus deleting it) and resetting the - associated modification flag. */ - if ( integrity_frame ) integrity_frame = astAnnul( integrity_frame ); - integrity_lost = 0; -} - -static void SetAttrib( AstObject *this_object, const char *setting, int *status ) { -/* -* Name: -* SetAttrib - -* Purpose: -* Set an attribute value for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void SetAttrib( AstObject *this, const char *setting, int *status ) - -* Class Membership: -* FrameSet member function (extends the astSetAttrib method -* inherited from the Frame class). - -* Description: -* This function assigns an attribute value for a FrameSet, 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 FrameSet. -* setting -* Pointer to a null terminated string specifying the new -* attribute value. -* status -* Pointer to the inherited status variable. - -* Attributes: -* The set of attribute values is not fixed and is determined by -* the current Frame. In addition, the FrameSet class defines the -* following attributes: -* -* Base (integer) -* Current (integer) - -* Notes: -* - This protected method is intended to be invoked by the Object -* astSet method and makes additional attributes accessible to it. -* - All attribute settings passed to this function are simply -* passed on to the corresponding method for the FrameSet's current -* Frame. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to a Frame within the FrameSet */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - const char *dom; /* Pointer to Domain string */ - int base; /* Base attribute value */ - int base_off; /* Offset of Base value string */ - int current; /* Current attribute value */ - int current_off; /* Offset of Current value string */ - int id; /* Offset of ID string */ - int invert; /* Invert attribute value */ - int len; /* Length of setting string */ - int nc; /* Number of characters read by astSscanf */ - int nfrm; /* Number of Frames in FrameSet */ - int report; /* Report attribute value */ - int variant; /* Offset of Variant string */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this_object); - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* Obtain the length of the setting string. */ - len = strlen( setting ); - -/* Test for each recognised attribute in turn, using "astSscanf" to parse the - setting string and extract the attribute value (or an offset to it in the - case of string values). In each case, use the value set in "nc" to check - that the entire string was matched. Once a value has been obtained, use the - appropriate method to set it. */ - -/* We first handle attributes that apply to the FrameSet as a whole - (rather than to the current Frame). */ - -/* Base. */ -/* ----- */ -/* Read as an integer. */ - if ( nc = 0, - ( 1 == astSscanf( setting, "base= %d %n", &base, &nc ) ) - && ( nc >= len ) ) { - astSetBase( this, base ); - -/* Also allow a string. */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "base= %n%*s %n", &base_off, &nc ) ) - && ( nc >= len ) ) { - -/* Check for "AST__CURRENT" or "Current". */ - if ( astChrMatch( "AST__CURRENT", setting + base_off ) || - astChrMatch( "Current", setting + base_off ) ) { - astSetBase( this, AST__CURRENT ); - -/* Check for "AST__BASE" or "Base" (possible, although not very - useful). */ - } else if ( astChrMatch( "AST__BASE", setting + base_off ) || - astChrMatch( "Base", setting + base_off ) ) { - -/* If the FrameSet contains a Frame with the given Domain name, make it - the base Frame. */ - } else { - nfrm = astGetNframe( this ); - for( base = 1; base <= nfrm; base++ ) { - fr = astGetFrame( this, base ); - dom = astGetDomain( fr ); - fr = astAnnul( fr ); - if( astChrMatch( dom, setting + base_off ) ) break; - } - - if( base <= nfrm ) { - astSetBase( this, base ); - -/* Report an error if the value wasn't recognised. */ - } else { - astError( AST__ATTIN, "astSetAttrib(%s): Invalid index value for " - "Base Frame \"%s\".", status, - astGetClass( this ), setting + base_off ); - } - } - -/* Current. */ -/* -------- */ -/* Since this determines the choice of current Frame, we must restore - the integrity state of the FrameSet before changing this attribute - and record the new integrity state afterwards. */ - -/* Read as an integer. */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "current= %d %n", ¤t, &nc ) ) - && ( nc >= len ) ) { - RestoreIntegrity( this, status ); - astSetCurrent( this, current ); - RecordIntegrity( this, status ); - -/* Also allow a string. */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "current= %n%*s %n", - ¤t_off, &nc ) ) - && ( nc >= len ) ) { - -/* Check for "AST__BASE" or "Base". */ - if ( astChrMatch( "AST__BASE", setting + current_off ) || - astChrMatch( "Base", setting + current_off ) ) { - RestoreIntegrity( this, status ); - astSetCurrent( this, AST__BASE ); - RecordIntegrity( this, status ); - -/* Check for "AST__CURRENT" or "Current" (possible, although not very - useful). */ - } else if ( astChrMatch( "AST__CURRENT", setting + current_off ) || - astChrMatch( "Current", setting + current_off ) ) { - -/* If the FrameSet contains a Frame with the given Domain name, make it - the current Frame. */ - } else { - nfrm = astGetNframe( this ); - for( current = 1; current <= nfrm; current++ ) { - fr = astGetFrame( this, current ); - dom = astGetDomain( fr ); - fr = astAnnul( fr ); - if( astChrMatch( dom, setting + current_off ) ) break; - } - - if( current <= nfrm ) { - RestoreIntegrity( this, status ); - astSetCurrent( this, current ); - RecordIntegrity( this, status ); - -/* Report an error if the value wasn't recognised. */ - } else { - astError( AST__ATTIN, "astSetAttrib(%s): Invalid index value for " - "Current Frame \"%s\".", status, - astGetClass( this ), setting + current_off ); - } - } - -/* ID. */ -/* --- */ - } else if ( nc = 0, ( 0 == astSscanf( setting, "id=%n%*[^\n]%n", &id, &nc ) ) - && ( nc >= len ) ) { - astSetID( this, setting + id ); - -/* Ident. */ -/* ------ */ - } else if ( nc = 0, ( 0 == astSscanf( setting, "ident=%n%*[^\n]%n", &id, &nc ) ) - && ( nc >= len ) ) { - astSetIdent( this, setting + id ); - -/* Invert. */ -/* ------- */ -/* Since this affects the choice of current Frame, we must restore the - integrity state of the FrameSet before changing this attribute and - record the new integrity state afterwards. */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "invert= %d %n", &invert, &nc ) ) - && ( nc >= len ) ) { - RestoreIntegrity( this, status ); - astSetInvert( this, invert ); - RecordIntegrity( this, status ); - -/* Report. */ -/* ------- */ - } else if ( nc = 0, - ( 1 == astSscanf( setting, "report= %d %n", &report, &nc ) ) - && ( nc >= len ) ) { - astSetReport( this, report ); - -/* Variant. */ -/* -------- */ - } else if ( nc = 0, - ( 0 == astSscanf( setting, "variant=%n%*[^\n]%n", &variant, &nc ) ) - && ( nc >= len ) ) { - astSetVariant( this, setting + variant ); - -/* 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 ) ) - -/* If the attribute was not recognised, use this macro to report an error - if a read-only attribute has been specified. */ - } else if ( MATCH( "allvariants" ) || - MATCH( "class" ) || - MATCH( "nframe" ) || - MATCH( "nin" ) || - MATCH( "nobject" ) || - MATCH( "nout" ) || - MATCH( "refcount" ) || - MATCH( "tranforward" ) || - MATCH( "traninverse" ) ) { - astError( AST__NOWRT, "astSet: The setting \"%s\" is invalid for a %s.", status, - setting, astGetClass( this ) ); - astError( AST__NOWRT, "This is a read-only attribute." , status); - -/* Pass unrecognised settings on to the FrameSet's current Frame for - further interpretation. */ - } else { - -/* Force a copy to be made of the current Frame, if needed, to make it - independent of other Frames within the FrameSet. */ - (void) ForceCopy( this, AST__CURRENT, status ); - -/* Obtain a pointer to the current Frame and invoke its astSetAttrib - method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astSetAttrib( fr, setting ); - fr = astAnnul( fr ); - -/* Note that the current Frame has been modified. */ - integrity_lost = 1; - } - -/* Undefine macros local to this function. */ -#undef MATCH -} - -static void SetAxis( AstFrame *this_frame, int axis, AstAxis *newaxis, int *status ) { -/* -* Name: -* SetAxis - -* Purpose: -* Set a new Axis for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void SetAxis( AstFrame *this, int axis, AstAxis *newaxis, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astSetAxis method -* inherited from the Frame class). - -* Description: -* This function allows a new Axis object to be associated with one -* of the axes of the current Frame in a FrameSet, 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 FrameSet. -* axis -* The index (zero-based) of the axis whose associated Axis -* object is to be replaced. -* newaxis -* Pointer to the new Axis object. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index supplied. */ - (void) astValidateAxis( this, axis, 1, "astSetAxis" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astSetAxis method to assign the new Axis object. Annul the - Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astSetAxis( fr, axis, newaxis ); - fr = astAnnul( fr ); -} - -static void SetBase( AstFrameSet *this, int iframe, int *status ) { -/* -*+ -* Name: -* astSetBase - -* Purpose: -* Set a value for the Base attribute of a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* void astSetBase( AstFrameSet *this, int iframe ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function sets a value for the Base attribute of a FrameSet. This -* value is an index that identifies the base Frame for the FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. -* iframe -* Value to be set for the Base attribute. - -* Notes: -* - A value of AST__BASE or AST__CURRENT may be given for the -* "iframe" parameter to identify the base Frame or the current -* Frame respectively. -*- -*/ - -/* Local Variables: */ - int invert; /* FrameSet is inverted? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Validate and translate the Frame index supplied. */ - iframe = astValidateFrameIndex( this, iframe, "astSetBase" ); - -/* Determine if the FrameSet has been inverted. */ - invert = astGetInvert( this ); - -/* If it has not been inverted, set the base Frame index, otherwise - set the current Frame index instead. */ - if ( astOK ) *( invert ? &this->current : &this->base ) = iframe; -} - -static void SetCurrent( AstFrameSet *this, int iframe, int *status ) { -/* -*+ -* Name: -* astSetCurrent - -* Purpose: -* Set a value for the Current attribute of a FrameSet. - -* Type: -* Protected function. - -* Synopsis: -* #include "frameset.h" -* int astSetCurrent( AstFrameSet *this, int iframe ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function sets a value for the Current attribute of a -* FrameSet. This attribute is an index that identifies the current -* Frame for the FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. -* iframe -* Value to be set for the Current attribute. - -* Notes: -* - A value of AST__BASE or AST__CURRENT may be given for the -* "iframe" parameter to identify the base Frame or the current -* Frame respectively. -*- -*/ - -/* Local Variables: */ - int invert; /* FrameSet is inverted? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Validate and translate the Frame index supplied. */ - iframe = astValidateFrameIndex( this, iframe, "astSetCurrent" ); - -/* Determine if the FrameSet has been inverted. */ - invert = astGetInvert( this ); - -/* If it has not been inverted, set the current frame index, otherwise - set the base Frame index instead. */ - if ( astOK ) *( invert ? &this->base : &this->current ) = iframe; -} - -static void SetVariant( AstFrameSet *this, const char *variant, int *status ) { -/* -*+ -* Name: -* astSetVariant - -* Purpose: -* Set a value for the Variant attribute of a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* void astSetVariant( AstFrameSet *this, const char *variant ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function sets a value for the Variant attribute of a FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. -* variant -* Value to be set for the Variant attribute. - -* Notes: -* - An error will be reported if the supplied variant name cannot be -* found in the Variants FrameSet associated with the current Frame. - -*- -*/ - -/* Local Variables: */ - AstCmpMap *map6; - AstCmpMap *map5; - AstCmpMap *map4; - AstFrame *frm; - AstFrame *vfrm; - AstFrameSet *tfs; - AstFrameSet *vfs; - AstMapping *map0; - AstMapping *map2; - AstMapping *map3; - AstMapping *map1; - char *myvar; - const char *dom; - int icur; - int ifrm; - int inode; - int inv0; - int inv; - int nfrm; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get a copy of the supplied string and clean it. */ - myvar = astStore( NULL, variant, strlen( variant ) + 1 ); - astRemoveLeadingBlanks( myvar ); - astChrCase( NULL, myvar, 1, 0 ); - if( astOK ) { - myvar[ astChrLen( myvar ) ] = 0; - -/* Get the one-based index of the Frame that defines the available - variant Mappings. */ - icur = GetVarFrm( this, astGetCurrent( this ), status ); - -/* Get the variants FrameSet from the Frame selected above. */ - frm = astGetFrame( this, icur ); - vfs = astGetFrameVariants( frm ); - -/* If there is no variants FrameSet in the Frame, the only allowed value - for "Variant" is the Domain name of the current Frame. */ - if( ! vfs ) { - dom = astGetDomain( this ); - if( astOK && strcmp( myvar, dom ) ) { - astError( AST__ATTIN, "astSetVariant(%s): Unknown Frame " - "variant '%s' requested.", status, astGetClass( this ), - myvar ); - } - -/* If there is a variants FrameSet in the Frame... */ - } else { - -/* Find the index of the Frame in the Variants FrameSet that has a Domain - equal to myvar. */ - nfrm = astGetNframe( vfs ); - for( ifrm = 0; ifrm < nfrm; ifrm++ ) { - vfrm = astGetFrame( vfs, ifrm + 1 ); - dom = astGetDomain( vfrm ); - vfrm = astAnnul( vfrm ); - if( !astOK || !strcmp( myvar, dom ) ) break; - } - -/* Report an error if no such Frame found. */ - if( ifrm == nfrm && astOK ) { - astError( AST__ATTIN, "astSetVariant(%s): Unknown Frame " - "variant '%s' requested - available variants are " - "'%s'.", status, astGetClass(this), myvar, - astGetAllVariants(this) ); - -/* Otherwise, get a Mapping from the current Frame in "this" to the - currently selected Variant Frame. We cannot assume that they are the - same as attributes of the current Frame (e.g. System) may have been - changed since the variant was added. If the required Frame is already - the current Frame, there is nothing more to do since the required - variant is already selected. */ - } else if( ifrm + 1 != astGetCurrent( vfs ) ){ - vfrm = astGetFrame( vfs, AST__CURRENT ); - dom = astGetDomain( frm ); - if( dom ) dom = astStore( NULL, dom, strlen( dom ) + 1 ); - astSetDomain( frm, astGetDomain( vfrm ) ); - tfs = astConvert( frm, vfrm, "" ); - astSetDomain( frm, dom ); - if( tfs ) { - map1 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); - tfs = astAnnul( tfs ); - vfrm = astAnnul( vfrm ); - -/* Get the Mapping from the original Variant Frame to the requested variant - Frame. */ - map2 = astGetMapping( vfs, AST__CURRENT, ifrm + 1 ); - -/* Get a Mapping from the new variant Frame to the current Frame in "this". */ - vfrm = astGetFrame( vfs, ifrm + 1 ); - astSetDomain( frm, astGetDomain( vfrm ) ); - tfs = astConvert( vfrm, frm, "" ); - astSetDomain( frm, dom ); - if( tfs ) { - map3 = astGetMapping( tfs, AST__BASE, AST__CURRENT ); - tfs = astAnnul( tfs ); - -/* Concatentate the three Mappings, to get the Mapping from the old - variant Frame to the new variant Frame. */ - map4 = astCmpMap( map1, map2, 1, " ", status ); - map5 = astCmpMap( map4, map3, 1, " ", status ); - -/* Now we modify the Mapping in the FrameSet. First get the index of the node - with which the Frame is associated. */ - inode = this->node[ icur - 1 ]; - -/* Get the Mapping that generates the node values, and its Invert flag. */ - map0 = this->map[ inode - 1 ]; - inv0 = this->invert[ inode - 1 ]; - -/* Temporarily reset the invert flag in the Mapping to account for any - changes made to the Mapping via other pointers. */ - inv = astGetInvert( map0 ); - astSetInvert( map0, inv0 ); - -/* Concatentate with "map5" to get the Mapping form the the parent node - to the new variant of the current node. */ - map6 = astCmpMap( map0, map5, 1, " ", status ); - -/* Simplify it and use it to replace the Mapping in the FrameSet structure. */ - this->map[ inode - 1 ] = astSimplify( map6 ); - this->invert[ inode - 1 ] = astGetInvert( this->map[ inode - 1 ] ); - -/* Re-instate the original Invert flag and free the old Mapping pointer. */ - astSetInvert( map0, inv ); - map0 = astAnnul( map0 ); - -/* Make the variant Frame the current Frame within the Variants FrameSet. */ - astSetCurrent( vfs, ifrm + 1 ); - -/* Free resources. */ - map6 = astAnnul( map6 ); - map5 = astAnnul( map5 ); - map4 = astAnnul( map4 ); - map3 = astAnnul( map3 ); - -/* Report an error if a Mapping cannot be found from the new variant Frame - to the current Frame in "this". */ - } else if( astOK ) { - astError( AST__INTER, "astSetVariant(%s): Cannot convert " - "from a %s with Domain '%s' to a %s with Domain " - "'%s' (internal programming error).", status, - astGetClass( this ), astGetClass( vfrm ), - astGetDomain( vfrm ), astGetClass( frm ), - astGetDomain( frm ) ); - } - -/* Free resources. */ - map2 = astAnnul( map2 ); - map1 = astAnnul( map1 ); - -/* Report an error if a Mapping cannot be found from the current Frame in - "this" to the current Variant Frame. */ - } else if( astOK ) { - astError( AST__INTER, "astSetVariant(%s): Cannot convert " - "from a %s with Domain '%s' to a %s with Domain " - "'%s' (internal programming error).", status, - astGetClass( this ), astGetClass( frm ), - astGetDomain( frm ), astGetClass( vfrm ), - astGetDomain( vfrm ) ); - } - -/* Free resources. */ - vfrm = astAnnul( vfrm ); - dom = astFree( (void *) dom ); - } - -/* Annul the pointer to the Variants FrameSet. */ - vfs = astAnnul( vfs ); - } - -/* Annul the pointer to the current Frame in "this". */ - frm = astAnnul( frm ); - } - -/* Free the memory holding the cleaned variant name. */ - myvar = astFree( myvar ); -} - -static AstMapping *Simplify( AstMapping *this_mapping, int *status ) { -/* -* Name: -* Simplify - -* Purpose: -* Simplify the Mappings in a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstMapping *Simplify( AstMapping *this, int *status ) - -* Class Membership: -* FrameSet method (over-rides the astSimplify method inherited -* from the Frame class). - -* Description: -* This function simplifies the Mappings in a FrameSet to eliminate -* redundant computational steps, or to merge separate steps which -* can be performed more efficiently in a single operation. - -* Parameters: -* this -* Pointer to the original FrameSet. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A new pointer to the (possibly simplified) FrameSet. If -* simplification was not possible, this will be a cloned pointer -* to the original FrameSet. - -* Notes: -* - A NULL pointer value will be returned if this function is -* invoked with the AST error status set, or if it should fail for -* any reason. -*/ - -/* Local Variables: */ - AstFrameSet *new; /* Pointer to new (simpler?) FrameSet */ - AstFrameSet *this; /* Pointer to original FrameSet structure */ - AstMapping *map; /* Pointer to Mapping */ - AstMapping *result; /* Result pointer to return */ - AstMapping *tmp; /* Temporary Mapping pointer */ - int inode; /* Loop counter for FrameSet nodes */ - int inv; /* Mapping Invert attribute value */ - int invert; /* Invert flag value */ - int set; /* Invert attribute set? */ - int simpler; /* Simplification achieved? */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_mapping; - -/* Make a copy of the FrameSet, since we may alter it (this is a deep - copy, which is a minor limitation of the current implementation). */ - new = astCopy( this ); - -/* Loop to examine each of the Mappings between the Frames in the - copy. */ - simpler = 0; - for ( inode = 1; astOK && ( inode < new->nnode ); inode++ ) { - -/* Obtain the Mapping pointer and associated invert flag. */ - map = new->map[ inode - 1 ]; - invert = new->invert[ inode - 1 ]; - -/* Determine if the Mapping's Invert attribute is set, and obtain its - value. */ - set = astTestInvert( map ); - inv = astGetInvert( map ); - -/* If necessary, set the required value for the Invert attribute. */ - if ( inv != invert ) astSetInvert( map, invert ); - -/* Simplify the Mapping. */ - tmp = astSimplify( map ); - -/* If necessary, restore the original state of the Mapping's Invert - attribute. */ - if ( inv != invert ) { - if ( set ) { - astSetInvert( map, inv ); - } else { - astClearInvert( map ); - } - } - -/* Test if simplification was performed. */ - if ( astOK ) { - if ( tmp != map ) { - -/* If so, annul the original Mapping pointer and substitute the new - one. Also set a new invert flag to accompany it. */ - (void) astAnnul( new->map[ inode - 1 ] ); - new->map[ inode - 1 ] = astClone( tmp ); - new->invert[ inode - 1 ] = astGetInvert( tmp ); - -/* Note if any Mapping within the FrameSet is simplified. */ - simpler = 1; - } - } - -/* Annul the pointer to the simplified Mapping. */ - tmp = astAnnul( tmp ); - } - -/* If simplification was possible, clone a pointer to the new - FrameSet. Otherwise clone a pointer to the original one. */ - if ( astOK ) result = astClone( simpler ? new : this ); - -/* Annul the new FrameSet pointer. */ - new = astAnnul( new ); - -/* If an error occurred, annul the returned pointer. */ - if ( !astOK ) result = astAnnul( result ); - -/* Return the result. */ - return result; -} - -static int Span( AstFrameSet *this, AstFrame **frames, int inode1, int inode2, - int avoid, AstMapping **map, int *forward, int *status ) { -/* -* Name: -* Span - -* Purpose: -* Find a path between two nodes in a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int Span( AstFrameSet *this, AstFrame **frames, int inode1, int inode2, -* int avoid, AstMapping **map, int *forward, int *status ) - -* Class Membership: -* FrameSet member function. - -* Description: -* This function searches a FrameSet to identify a path between two -* specified nodes. It returns an array of pointers to each Mapping -* in the path, along with direction information, so that an -* overall Mapping between the two nodes can be constructed. - -* Parameters: -* this -* Pointer to the FrameSet. -* frames -* Pointer to an array of Frame pointers, indexed by node index. -* Nodes which have no associated Frame will have a NULL pointer -* stored in this array. -* inode1 -* Zero based index of the starting node. -* inode2 -* Zero based index of the ending node. -* avoid -* Zero based index which identifies a node which is to be -* avoided (i.e. the initial step in the path should not be via -* this node). This value is required because the function -* invokes itself recursively; it provides a mechanism to -* prevent searches proceeding back down paths that have already -* been searched. External callers should provide a value of -1, -* which indicates that all possible paths should initially be -* explored. -* map -* Pointer to the start of an array that will be filled with a -* series of pointers to Mappings which must be applied in turn -* in order to transform between the two Frames. External -* callers should ensure that this array contains at least as many -* elements as there are Mappings and Frames in the FrameSet (one less -* than the number of nodes plus the number of Frames). -* -* Note that the pointers are simply copies of addresses from -* the FrameSet's "map" array. They are not cloned, so should -* not be annulled by the caller. -* forward -* Pointer to the start of an array of int that will be filled -* with boolean flags (0 or 1) to indicate whether the forward -* (as opposed to the inverse) transformation should be used for -* each Mapping returned in order to effect the transformation -* between the starting and ending nodes. This array should be the -* same size as the "map" array. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The function returns one more than the number of Mappings -* required to perform the transformation, or zero if it was not -* possible to find a path between the two nodes. - -* Notes: -* - If a node has an associated Frame, the Frame usually represents -* a UnitMap and so can be ignored. The exception is if the Frame is -* actually a Region (or a CmpFrame containing a Region), in which -* case it represents a Mapping which returns bad values if the -* input position is outside the Region. This form of Mapping should -* not be ignored, and so the returned list of Mappings includes the -* effect of any Frames along the path which are not equivalent to a -* UnitMap. This equivalence is determined by invoking the astSimplify -* method on the Frame. -* - 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. -* - On the assumption that the FrameSet has been consistently -* constructed, there should be exactly one path between any pair -* of its nodes. It should not, therefore, ever fail to find a -* path except when invoked recursively to explore a subset of the -* FrameSet's nodes (this should not be visible to an external -* caller). Failure to find a path does not in itself result in an -* error condition. -*/ - -/* Local Variables: */ - AstFrame *frame; /* Pointer to Frame associated with inode1 */ - int fwd; /* Forward Mapping identified? */ - int inode; /* Loop counter for nodes */ - int inv; /* Inverse Mapping identified? */ - int invert; /* Original Mapping Invert value */ - int nextra; /* No. of extra Mappings to add to path */ - int result; /* Count of mappings (to be returned) */ - -/* Check the global error status. */ - if ( !astOK ) return 0; - -/* See if the two nodes are the same. */ - result = ( inode1 == inode2 ); - -/* If so, we need to consider the Mapping represented by any Frame - associated with the node. Most classes of Frames are equivalent to a - UnitMap and so can be ignored. But some (e.g. the Region class) - are not equivalent to a UnitMap and so needs to be included in the - returned Mapping list. */ - if( result ) { - result = 1; - -/* If inode1 is associated with a Frame, which is not equivalent to a - UnitMap, add the Frame as the first Mapping into the returned list. The - "forward" value is irrelevant since the forward and inverse transformations - of Frames are the same. */ - frame = frames[ inode1 ]; - if( frame ) { - if( !astIsUnitFrame( frame ) ) { - result++; - *map = (AstMapping *) frame; - *forward = 1; - } - } - -/* If the nodes are different, we now attempt to find the next step in - the path between them. Loop through all available nodes looking for - the next one to transform to (i.e. one that is directly related by - a Mapping to our starting node). */ - } else { - for ( inode = 0; inode < this->nnode; inode++ ) { - -/* Do not consider node "avoid". This prevents us re-tracing our steps - backwards when this function is invoked recursively. */ - if ( inode != avoid ) { - -/* Test if inode is derived from inode1 (if so, the Mapping associated - with inode will convert from inode1 to inode when applied in the - forward direction). */ - fwd = ( inode > 0 ) && ( this->link[ inode - 1 ] == inode1 ); - -/* Test if inode1 is derived from inode (if so, the Mapping associated - with inode1 will convert from inode1 to inode when applied in the - inverse direction). */ - inv = ( inode1 > 0 ) && ( this->link[ inode1 - 1 ] == inode ); - -/* If the nodes are directly related, we try to find a path from inode to - inode2 without going back through inode1. */ - if ( fwd || inv ) { - -/* If node1 is associated with a Frame, we need to include the Frame - as a Mapping in the returned list unless the Frame is equivalent to a - UnitMap. Note the number of slots to be reserved for node1 when we call - Span recursively below. */ - nextra = 1; - frame = frames[ inode1 ]; - if( frame && !astIsUnitFrame( frame ) ) nextra = 2; - -/* Invoke this function recursively to try and find a path from inode - to inode2 without going back through inode1. If this is possible, a - non-zero result will be returned. Store the returned Mappings and - direction information in the arrays supplied, but leave extra space to - insert information about the Mapping between nodes inode1 and inode. */ - result = Span( this, frames, inode, inode2, inode1, - map + nextra, forward + nextra, status ); - -/* If a path was found, increment the Mapping count to account for the - one that transforms between nodes inode1 and inode and insert - information for this Mapping into the output arrays. */ - if ( result ) { - result++; - nextra--; - map[ nextra ] = this->map[ ( fwd ? inode : inode1 ) - 1 ]; - forward[ nextra ] = fwd; - -/* Obtain the original value of the Invert attribute for the Mapping - between nodes inode1 and inode (recorded when the Mapping was first - added to the FrameSet). Test if this value has now changed. If so, - some external code has inverted the Mapping via another pointer, so - invert the returned direction information to compensate for - this. */ - invert = this->invert[ ( fwd ? inode : inode1 ) - 1 ]; - if ( invert != astGetInvert( map[ nextra ] ) ) { - forward[ nextra ] = !forward[ nextra ]; - } - -/* If inode1 is associated with a non-unit Frame Mapping, add the Frame - Mapping in as the first Mapping in the returned list. The "forward" value - is irrelevant since the forward and inverse transformations of Frames - are the same. */ - if( nextra ) { - result++; - *map = (AstMapping *) frame; - *forward = 1; - } - -/* Quit searching once a path has been found. */ - break; - } - } - } - } - } - -/* Return the result, which is one more than the number of mappings - found (i.e. steps in the path), or zero if no path was found (this - should only occur when invoked recursively to explore an - unsuccessful sub-path). */ - return result; -} - -static int SubFrame( AstFrame *this_frame, AstFrame *template, - int result_naxes, - const int *target_axes, const int *template_axes, - AstMapping **map, AstFrame **result, int *status ) { -/* -* Name: -* SubFrame - -* Purpose: -* Select axes from a FrameSet and convert to the new coordinate system. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int SubFrame( AstFrame *target, AstFrame *template, int result_naxes, -* const int *target_axes, const int *template_axes, -* AstMapping **map, AstFrame **result, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astSubFrame -* method inherited from the Frame class). - -* Description: -* This function selects a requested sub-set (or super-set) of the -* axes from the current Frame of a "target" FrameSet and creates a -* new Frame with copies of the selected axes assembled in the -* requested order. It then optionally overlays the attributes of a -* "template" Frame on to the result. It returns both the resulting -* Frame and a Mapping that describes how to convert between the -* coordinate systems described by the current Frame of the target -* FrameSet and the result Frame. If necessary, this Mapping takes -* account of any differences in the Frames' attributes due to the -* influence of the template. - -* Parameters: -* target -* Pointer to the target FrameSet, from whose current Frame the -* axes are to be selected. -* template -* Pointer to the template Frame, from which new attributes for -* the result Frame are to be obtained. Optionally, this may be -* NULL, in which case no overlaying of template attributes will -* be performed. -* result_naxes -* Number of axes to be selected from the target FrameSet. This -* number may be greater than or less than the number of axes in -* the FrameSet's current Frame (or equal). -* target_axes -* Pointer to an array of int with result_naxes elements, giving -* a list of the (zero-based) axis indices of the axes to be -* selected from the current Frame of the target FrameSet. 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 FrameSet, but will be assigned -* default attributes instead. -* template_axes -* Pointer to an array of int with result_naxes elements. This -* should contain a list of the template axes (given as -* zero-based axis indices) with which the axes of the result -* Frame are to be associated. This array determines which axes -* are used when overlaying axis-dependent attributes of the -* template on to the result. If any element of this array is -* set to -1, the corresponding result axis will not receive any -* template attributes. -* -* If the template argument is given as NULL, this array is not -* used and a NULL pointer may also be supplied here. -* map -* Address of a location to receive a pointer to the returned -* Mapping. The forward transformation of this Mapping will -* describe how to convert coordinates from the coordinate -* system described by the current Frame of the target FrameSet -* to that described by the result Frame. The inverse -* transformation will convert in the opposite direction. -* result -* Address of a location to receive a pointer to the result Frame. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* A non-zero value is returned if coordinate conversion is -* possible between the current Frame of the target FrameSet and -* the result Frame. Otherwise zero is returned and *map and -* *result are returned as NULL (but this will not in itself result -* in an error condition). In general, coordinate conversion should -* always be possible if no template Frame is supplied but may not -* always be possible otherwise. - -* Notes: -* - A value of zero will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to FrameSet's current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int match; /* Result to be returned */ - -/* Initialise. */ - *map = NULL; - *result = NULL; - match = 0; - -/* Check the global error status. */ - if ( !astOK ) return match; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame. */ - fr = astGetFrame( this, AST__CURRENT ); - -/* Invoke the astSubFrame method for this Frame. */ - match = astSubFrame( fr, template, result_naxes, target_axes, template_axes, - map, result ); - -/* Annul the Frame pointer. */ - fr = astAnnul( fr ); - -/* If an error occurred, clean up by annulling any returned objects and clear - the returned result. */ - if ( !astOK ) { - *map = astAnnul( *map ); - *result = astAnnul( *result ); - match = 0; - } - -/* Return the result. */ - return match; -} - -static AstSystemType SystemCode( AstFrame *this_frame, const char *system, int *status ) { -/* -* Name: -* SystemCode - -* Purpose: -* Convert a string into a coordinate system type code. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstSystemType SystemCode( AstFrame *this, const char *system, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astSystemCode -* method inherited from the Frame class). - -* Description: -* This function converts a string used for the external description of -* a coordinate system into a Frame coordinate system type code (System -* attribute value). It is the inverse of the astSystemString function. - -* Parameters: -* this -* Pointer to the Frame. -* system -* Pointer to a constant null-terminated string containing the -* external description of the coordinate system. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The System type code. - -* Notes: -* - A value of AST__BADSYSTEM is returned if the coordinate system -* description was not recognised. This does not produce an error. -* - A value of AST__BADSYSTEM is also returned if this function -* is invoked with the global error status set or if it should fail -* for any reason. -*/ - -/* Local Variables: */ - AstSystemType result; /* Result value to return */ - AstFrame *fr; /* Pointer to FrameSet's current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Initialise. */ - result = AST__BADSYSTEM; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astSystemCode method for this Frame. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astSystemCode( fr, system ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = AST__BADSYSTEM; - -/* Return the result. */ - return result; -} - -static const char *SystemString( AstFrame *this_frame, AstSystemType system, int *status ) { -/* -* Name: -* SystemString - -* Purpose: -* Convert a coordinate system type code into a string. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* const char *SystemString( AstFrame *this, AstSystemType system, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astSystemString -* method inherited from the Frame class). - -* Description: -* This function converts a Frame coordinate system type code -* (System attribute value) into a string suitable for use as an -* external representation of the coordinate system type. - -* Parameters: -* this -* Pointer to the Frame. -* system -* The coordinate system type code. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Pointer to a constant null-terminated string containing the -* textual equivalent of the type code supplied. - -* Notes: -* - A NULL pointer value is returned if the coordinate system -* code was not recognised. This does not produce an error. -* - A NULL pointer value is also returned if this function is -* invoked with the global error status set or if it should fail -* for any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to FrameSet's current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - const char *result; /* Pointer value to return */ - -/* Initialise. */ - result = NULL; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astSystemString method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astSystemString( fr, system ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = NULL; - -/* Return the result pointer. */ - return result; - -} - -static int TestAttrib( AstObject *this_object, const char *attrib, int *status ) { -/* -* Name: -* TestAttrib - -* Purpose: -* Test if a specified attribute value is set for a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int TestAttrib( AstObject *this, const char *attrib, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astTestAttrib protected -* method inherited from the Frame class). - -* Description: -* This function returns a boolean result (0 or 1) to indicate whether -* a value has been set for one of a FrameSet's attributes. - -* Parameters: -* this -* Pointer to the FrameSet. -* attrib -* Pointer to a null terminated string specifying the attribute -* name. This should be in lower case with no surrounding white -* space. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* One if a value has been set, otherwise zero. - -* Notes: -* - A value of zero will be returned if this function is invoked -* with the global status set, or if it should fail for any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int result; /* Result value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* Check the attribute name and test the appropriate attribute. */ - -/* We first handle attributes that apply to the FrameSet as a whole - (rather than to the current Frame). */ - -/* Base. */ -/* ----- */ - if ( !strcmp( attrib, "base" ) ) { - result = astTestBase( this ); - -/* Current. */ -/* -------- */ - } else if ( !strcmp( attrib, "current" ) ) { - result = astTestCurrent( this ); - -/* ID. */ -/* --- */ - } else if ( !strcmp( attrib, "id" ) ) { - result = astTestID( this ); - -/* Ident. */ -/* ------ */ - } else if ( !strcmp( attrib, "ident" ) ) { - result = astTestIdent( this ); - -/* Invert. */ -/* ------- */ - } else if ( !strcmp( attrib, "invert" ) ) { - result = astTestInvert( this ); - -/* Report. */ -/* ------- */ - } else if ( !strcmp( attrib, "report" ) ) { - result = astTestReport( this ); - -/* Variant. */ -/* -------- */ - } else if ( !strcmp( attrib, "variant" ) ) { - result = astTestVariant( this ); - -/* If the name is not recognised, test if it matches any of the - read-only attributes of this class. If it does, then return - zero. */ - } else if ( !strcmp( attrib, "allvariants" ) || - !strcmp( attrib, "class" ) || - !strcmp( attrib, "nframe" ) || - !strcmp( attrib, "nin" ) || - !strcmp( attrib, "nobject" ) || - !strcmp( attrib, "nout" ) || - !strcmp( attrib, "refcount" ) || - !strcmp( attrib, "tranforward" ) || - !strcmp( attrib, "traninverse" ) ) { - result = 0; - -/* Pass unrecognised attributes on to the FrameSet's current Frame for - further interpretation. */ - } else { - -/* Obtain a pointer to the current Frame and invoke its astTestAttrib - method. Annul the Frame pointer afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astTestAttrib( fr, attrib ); - fr = astAnnul( fr ); - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result, */ - return result; -} - -static int TestBase( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astTestBase - -* Purpose: -* Determine if a value has been set for the Base attribute of a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* int astTestBase( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns a boolean result to indicate if a value -* has been set for the Base attribute of a FrameSet. This -* attribute is an index that identifies the base Frame in the -* FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* Zero or 1, depending on whether a value has been set. - -* 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: */ - int invert; /* FrameSet is inverted? */ - int result; /* Value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Determine if the FrameSet has been inverted. */ - invert = astGetInvert( this ); - -/* If it has not been inverted, test the base Frame index, otherwise - test the index of the current Frame instead. */ - if ( astOK ) { - if ( !invert ) { - result = ( this->base != -INT_MAX ); - } else { - result = ( this->current != -INT_MAX ); - } - } - -/* Return the result. */ - return result; -} - -static int TestCurrent( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astTestCurrent - -* Purpose: -* Test if a value has been set for the Current attribute of a FrameSet. - -* Type: -* Protected function. - -* Synopsis: -* #include "frameset.h" -* int astTestCurrent( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns a boolean result to indicate whether a -* value has been set for the Current attribute of a FrameSet. -* This attribute is an index that identifies the current Frame in -* a FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* Zero or 1, depending on whether a value has been set. - -* 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: */ - int invert; /* FrameSet is inverted? */ - int result; /* Value to return */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Determine if the FrameSet has been inverted. */ - invert = astGetInvert( this ); - -/* If it has not been inverted, test the current Frame index, - otherwise test the index of the base Frame instead. */ - if ( astOK ) { - if ( !invert ) { - result = ( this->current != -INT_MAX ); - } else { - result = ( this->base != -INT_MAX ); - } - } - -/* Return the result. */ - return result; -} - -static int TestVariant( AstFrameSet *this, int *status ) { -/* -*+ -* Name: -* astTestVariant - -* Purpose: -* Determine if a value has been set for the Variant attribute of a FrameSet. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* int astTestVariant( AstFrameSet *this ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns a boolean result to indicate if a value -* has been set for the Variant attribute of a FrameSet. - -* Parameters: -* this -* Pointer to the FrameSet. - -* Returned Value: -* Zero or 1, depending on whether a value has been set. - -* 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 *frm; - AstFrameSet *vfs; - int result; - int icur; - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Get the one-based index of the Frame to use. */ - icur = GetVarFrm( this, astGetCurrent( this ), status ); - -/* Get a pointer to the Variants FrameSet in the current Frame. */ - frm = astGetFrame( this, icur ); - vfs = astGetFrameVariants( frm ); - -/* If it is null, return zero, otherwise 1. */ - result = vfs ? 1 : 0; - -/* Annul pointers. */ - if( vfs ) vfs = astAnnul( vfs ); - frm = astAnnul( frm ); - -/* Return the result. */ - return result; -} - -static void TidyNodes( AstFrameSet *this, int *status ) { -/* -* Name: -* TidyNodes - -* Purpose: -* Tidy the nodes in a FrameSet. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void TidyNodes( AstFrameSet *this, int *status ) - -* Class Membership: -* FrameSet member function. - -* Description: -* This function tidies the nodes in a FrameSet, removing any that -* are unnecessary or represent dead-ends. It should be used after -* any changes have been made to a FrameSet that may have reduced -* the number of references to any of its nodes (either by Frames -* or by other nodes). - -* Parameters: -* this -* Pointer to the FrameSet. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - AstMapping *newmap; /* Pointer to simplified Mapping */ - AstMapping *tmpmap; /* Pointer to new compound Mapping */ - int ifr; /* Loop counter for Frames */ - int inode; /* Loop counter for nodes */ - int last_link[ 2 ]; /* Last nodes to reference via "link" array */ - int link_ref; /* Number of "link" array references */ - int needed; /* Node still required? */ - int next; /* Node which references the removed one */ - int remove; /* Node to be removed */ - int suspect; /* Loop counter for testing nodes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Loop to search for unnecessary nodes until no more are found. */ - needed = 0; - while ( !needed ) { - -/* Inspect each node (including node zero, which does not actually - have a Mapping associated with it) to see how many times it is - referenced. */ - for ( suspect = 0; suspect < this->nnode; suspect++ ) { - link_ref = 0; - -/* Test for at least one reference from within the "node" array which - associates Frames with particular nodes. */ - for ( ifr = 1; ifr <= this->nframe; ifr++ ) { - if ( ( needed = ( this->node[ ifr - 1 ] == suspect ) ) ) break; - } - -/* If no references were found above, look for references in the - "link" array that inter-connects all the nodes. */ - if ( !needed ) { - for ( inode = 1; inode < this->nnode; inode ++ ) { - if ( this->link[ inode - 1 ] == suspect ) { - -/* Node zero must be retained if it has more than two links - referencing it, while other nodes only require more than one. */ - if ( ( needed = ( link_ref >= ( suspect ? 1 : 2 ) ) ) ) break; - -/* Remember (up to) the first two nodes which reference the current one. */ - last_link[ link_ref++ ] = inode; - } - } - } - -/* If there were insufficient references to retain this node, we must - now decide why it should be removed. */ - if ( !needed ) { - -/* If there is no Frame associated with a node and there are less than - two links to it (for node zero), or less then one link (for other - nodes), then the there is no route to anything else via this node. - It is a dead-end. */ - if ( link_ref < ( suspect ? 1 : 2 ) ) { - -/* To tidy up, we remove the affected node or, for node zero, the - remaining one that references it. Annul the Mapping associated with - the node being removed. */ - remove = suspect ? suspect : last_link[ 0 ]; - this->map[ remove - 1 ] = astAnnul( this->map[ remove - 1 ] ); - -/* If an unnecessary node is not a dead-end, then it is a redundant - node which simply joins two Mappings. */ - } else { - -/* To tidy up, we remove the affected node or, for node zero, the - first one that references it. */ - remove = suspect ? suspect : last_link[ 0 ]; - -/* We then produce a compound Mapping which spans the gap by - concatenating the Mappings associated with the node being removed - and the remaining one which references it. For node zero, the first - of these Mappings must be inverted because there are no out-going - Mappings from node zero. */ - next = suspect ? last_link[ 0 ] : last_link[ 1 ]; - tmpmap = CombineMaps( this->map[ remove - 1 ], - this->invert[ remove - 1 ] != !suspect, - this->map[ next - 1 ], - this->invert[ next - 1 ], 1, status ); - -/* Simplify this compound Mapping. */ - newmap = astSimplify( tmpmap ); - tmpmap = astAnnul( tmpmap ); - -/* Annul the individual Mapping pointers. */ - this->map[ remove - 1 ] = astAnnul( this->map[ remove - 1 ] ); - this->map[ next - 1 ] = astAnnul( this->map[ next - 1 ] ); - -/* Install the new compound Mapping and its Invert flag. */ - this->map[ next - 1 ] = newmap; - this->invert[ next - 1 ] = astGetInvert( newmap ); - -/* Transfer the "link" value from the removed node to the one which - takes its place. */ - this->link[ next - 1 ] = this->link[ remove - 1 ]; - } - -/* Loop to move all subsequent node data down in the "map", "invert" - and "link" arrays to close the gap where a node has been - removed. */ - for ( inode = remove; inode < this->nnode - 1; inode ++ ) { - this->map [ inode - 1 ] = this->map[ inode ]; - this->link [ inode - 1 ] = this->link[ inode ]; - this->invert[ inode - 1 ] = this->invert[ inode ]; - } - this->map[ this->nnode - 2 ] = NULL; - this->link[ this->nnode - 2 ] = -1; - this->invert[ this->nnode - 2 ] = -1; - -/* Decrement the node count. */ - this->nnode--; - -/* Loop to adjust each entry in the "node" array for the change in - node numbering, re-directing references to the removed node towards - the new node zero. */ - for ( ifr = 1; ifr <= this->nframe; ifr++ ) { - if ( this->node[ ifr - 1 ] > remove ) { - this->node[ ifr - 1 ]--; - } else if ( this->node[ ifr - 1 ] == remove ) { - this->node[ ifr - 1 ] = 0; - } - } - -/* Similarly adjust each entry in the "link" array. */ - for ( inode = 1; inode < this->nnode; inode++ ) { - if ( this->link[ inode - 1 ] > remove ) { - this->link[ inode - 1 ]--; - } else if ( this->link[ inode - 1 ] == remove ) { - this->link[ inode - 1 ] = 0; - } - } - -/* Once a node has been removed, other nodes (perhaps already tested) - may no longer be needed, so quit the testing loop and start testing - again with node zero. The process terminates when no more - unnecessary nodes can be found. */ - break; - } - } - } -} - -static AstPointSet *Transform( AstMapping *this_mapping, AstPointSet *in, - int forward, AstPointSet *out, int *status ) { -/* -* Name: -* Transform - -* Purpose: -* Transform a set of points. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* AstPointSet *Transform( AstMapping *this, AstPointSet *in, -* int forward, AstPointSet *out, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the astTransform method -* inherited from the Frame class). - -* Description: -* This function takes a FrameSet and a set of points encapsulated -* in a PointSet, and applies either the forward or inverse -* coordinate transformation (if defined by the FrameSet) to the -* points. The forward transformation converts between the -* FrameSet's base Frame and its current Frame, while the inverse -* transformation converts in the opposite direction. - -* Parameters: -* this -* Pointer to the FrameSet. -* in -* Pointer to the PointSet holding the input coordinate data. -* forward -* A non-zero value indicates that the forward coordinate transformation -* should be applied, while a zero value requests the inverse -* transformation. -* out -* Pointer to a PointSet which will hold the transformed (output) -* coordinate values. A NULL value may also be given, in which case a -* new PointSet will be created by this function. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* Pointer to the output (possibly new) PointSet. - -* Notes: -* - An error will result if the FrameSet supplied does not define -* the requested coordinate transformation (either forward or -* inverse). -* - The number of coordinate values per point in the input -* PointSet must match the number of input coordinates for the -* FrameSet being applied (or number of output coordinates if the -* inverse transformation is requested). This will be equal to the -* number of axes in the FrameSet's base Frame (or the current -* Frame for the inverse transformation). -* - If an output PointSet is supplied, it must have space for -* sufficient number of points and coordinate values per point to -* accommodate the result (e.g. the number of FrameSet output -* coordinates, or number of input coordinates if the inverse -* transformation is requested). Any excess space will be ignored. -* - A null pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - AstMapping *map; /* Pointer to the base->current Mapping */ - AstPointSet *result; /* Pointer value to return */ - -/* Check the global error status. */ - if ( !astOK ) return NULL; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_mapping; - -/* Obtain the Mapping between the base and current Frames in the - FrameSet (note this takes account of whether the FrameSet has been - inverted). */ - map = astGetMapping( this, AST__BASE, AST__CURRENT ); - -/* Apply the Mapping to the input PointSet. */ - result = astTransform( map, in, forward, out ); - -/* Annul the Mapping pointer. */ - map = astAnnul( map ); - -/* If an error has occurred and a new PointSet may have been created, then - clean up by annulling it. In any case, ensure that a NULL result is - returned.*/ - if ( !astOK ) { - if ( !out ) result = astAnnul( result ); - result = NULL; - } - -/* Return a pointer to the output PointSet. */ - return result; -} - -static int Unformat( AstFrame *this_frame, int axis, const char *string, - double *value, int *status ) { -/* -* Name: -* Unformat - -* Purpose: -* Read a formatted coordinate value for a FrameSet axis. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int Unformat( AstFrame *this, int axis, const char *string, -* double *value, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the public astUnformat -* method inherited from the Frame class). - -* Description: -* This function reads a formatted coordinate value for a FrameSet -* 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 FrameSet. -* axis -* The number of the FrameSet axis for which the coordinate -* value is to be read (axis numbering starts at zero for the -* first axis). -* string -* Pointer to a constant null-terminated string containing the -* formatted coordinate value. -* value -* Pointer to a double in which the coordinate value read will be -* returned. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The number of characters read from the string to obtain the -* coordinate value. - -* Notes: -* - Any white space at the beginning of the string will be -* skipped, as also will any trailing white space following the -* coordinate value read. The function's return value will reflect -* this. -* - A function value of zero (and no coordinate value) will be -* returned, without error, if the string supplied does not contain -* a suitably formatted value. -* - The string "<bad>" is recognised as a special case and will -* generate the value AST__BAD, without error. The test for this -* string is case-insensitive and permits embedded white space. -* - A function result of zero will be returned and no coordinate -* value will be returned via the "value" pointer if this function -* is invoked with the global error status set, or if it should -* fail for any reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - double coord; /* Coordinate value read */ - int nc; /* Number of characters read */ - -/* Initialise. */ - nc = 0; - -/* Check the global error status. */ - if ( !astOK ) return nc; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Validate the axis index. */ - (void) astValidateAxis( this, axis, 1, "astUnformat" ); - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astUnformat method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - nc = astUnformat( fr, axis, string, &coord ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the number of characters read. */ - if ( !astOK ) { - nc = 0; - -/* Otherwise, if characters were read, return the coordinate value. */ - } else if ( nc ) { - *value = coord; - } - -/* Return the number of characters read. */ - return nc; -} - -static int ValidateAxis( AstFrame *this_frame, int axis, int fwd, - const char *method, int *status ) { -/* -* Name: -* ValidateAxis - -* Purpose: -* Validate and permute a FrameSet's axis index. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int ValidateAxis( AstFrame *this, int axis, int fwd, const char *method, -* int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected -* astValidateAxis method inherited from the Frame class). - -* Description: -* This function checks the validity of an index (zero-based) which -* is to be used to address one of the coordinate axes of the -* current Frame in a FrameSet. If the index is valid, it is -* permuted using the axis permutation array associated with the -* FrameSet's current Frame and the (zero-based) permuted axis -* index is returned. This gives the index the axis had when the -* Frame was first created. If the axis index supplied is not -* valid, an error is reported and the global error status is set. - -* Parameters: -* this -* Pointer to the FrameSet. -* 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 -* FrameSet's current Frame. -* fwd -* If non-zero, the suppplied axis index is assumed to be an -* "external" axis index, and the corresponding "internal" axis index -* is returned as the function value. Otherwise, the suppplied axis -* index is assumed to be an "internal" axis index, and the -* corresponding "external" axis index is returned as the function -* value. -* method -* Pointer to a constant null-terminated character string -* containing the name of the method that invoked this function -* to validate an axis index. This method name is used solely -* for constructing error messages. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The permuted axis index - either "internal" or "external" as -* specified by "fwd". - -* Notes: -* - A value of zero will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - int naxes; /* Number of FrameSet axes */ - int result; /* Permuted axis index */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Determine the number of FrameSet axes. */ - naxes = astGetNaxes( this ); - if ( astOK ) { - -/* If the FrameSet has no axes, report an error (convert to 1-based - axis numbering for the benefit of the public interface). */ - if ( naxes == 0 ) { - astError( AST__AXIIN, "%s(%s): Invalid attempt to use an axis index " - "(%d) for a %s which has no axes.", status, method, - astGetClass( this ), axis + 1, astGetClass( this ) ); - -/* Otherwise, check the axis index for validity and report an error if - it is not valid (again, convert to 1-based axis numbering). */ - } else if ( ( axis < 0 ) || ( axis >= naxes ) ) { - astError( AST__AXIIN, "%s(%s): Axis index (%d) invalid - it should " - "be in the range 1 to %d.", status, method, astGetClass( this ), - axis + 1, naxes ); - -/* If the axis index was valid, obtain a pointer to the FrameSet's - current Frame and invoke this Frame's astValidateAxis method to - obtain the permuted axis index. Annul the Frame pointer - afterwards. */ - } else { - fr = astGetFrame( this, AST__CURRENT ); - result = astValidateAxis( fr, axis, fwd, "astValidateAxis" ); - fr = astAnnul( fr ); - } - } - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = 0; - -/* Return the result. */ - return result; -} - -static void ValidateAxisSelection( AstFrame *this_frame, int naxes, - const int *axes, const char *method, int *status ) { -/* -* Name: -* ValidateAxisSelection - -* Purpose: -* Check that a set of axes selected from a Frame is valid. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void ValidateAxisSelection( AstFrame *this, int naxes, -* const int *axes, const char *method, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astValidateAxisSelection -* method inherited from the Frame class). - -* Description: -* This function checks the validity of an array of (zero-based) -* axis indices that specify a set of axes to be selected from a -* Frame. To be valid, no axis should be selected more than -* once. In assessing this, any axis indices that do not refer to -* valid Frame axes (e.g. are set to -1) are ignored. -* -* If the axis selection is valid, this function returns without further -* action. Otherwise, an error is reported and the global error status is -* set. - -* Parameters: -* this -* Pointer to the Frame. -* naxes -* The number of axes to be selected (may be zero). -* axes -* Pointer to an array of int with naxes elements that contains the -* (zero based) axis indices to be checked. -* method -* Pointer to a constant null-terminated character string -* containing the name of the method that invoked this function -* to validate an axis selection. This method name is used -* solely for constructing error messages. -* status -* Pointer to the inherited status variable. -*/ - -/* Local Variables: */ - AstFrame *fr; /* Pointer to current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke this - Frame's astValidateAxisSelection method. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - astValidateAxisSelection( fr, naxes, axes, method ); - fr = astAnnul( fr ); - -} - -static int ValidateFrameIndex( AstFrameSet *this, int iframe, - const char *method, int *status ) { -/* -*+ -* Name: -* astValidateFrameIndex - -* Purpose: -* Validate a FrameSet Frame index number. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* int astValidateFrameIndex( AstFrameSet *this, int iframe, -* const char *method ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function checks a (one-based) FrameSet Frame index for -* validity. If it is not valid, an error is reported. Otherwise, -* the function returns the Frame index value, having translated -* the special values AST__CURRENT and AST__BASE into valid Frame -* indices if necessary. - -* Parameters: -* this -* Pointer to the FrameSet. -* iframe -* The Frame index. To be valid this should lie in the range 1 -* to the number of Frames in the FrameSet. In addition, the -* values AST__CURRENT and AST__BASE may be given to indicate -* the "current" and "base" Frames. These values will be -* translated into the acceptable range. -* method -* Pointer to a constant null-terminated character string -* containing the name of the method that invoked this function -* to validate a Frame index. This method name is used solely -* for constructing error messages. - -* Returned Value: -* The validated (one-based) Frame index. - -* 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 -* (e.g. if the Frame index is invalid). -*- -*/ - -/* Local Variables: */ - int nframe; /* Number of Frames */ - int result; /* Returned index value */ - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Check if the base or current Frame was specified and retrieve the - required Frame index from the FrameSet. */ - if ( iframe == AST__BASE ) { - result = astGetBase( this ); - } else if ( iframe == AST__CURRENT ) { - result = astGetCurrent( this ); - -/* Otherwise, determine how many Frames there are in the FrameSet. */ - } else { - nframe = astGetNframe( this ); - if ( astOK ) { - -/* Check that the supplied index is within range and report an error - if it is not. */ - if ( ( iframe < 1 ) || ( iframe > nframe ) ) { - astError( AST__FRMIN, "%s(%s): Invalid Frame index (%d) given.", status, - method, astGetClass( this ), iframe ); - astError( AST__FRMIN, "This value should be in the range 1 to " - "%d (or AST__CURRENT or AST__BASE).", status, nframe ); - -/* If OK, return the validated index value. */ - } else { - result = iframe; - } - } - } - -/* Return the result. */ - return result; -} - -static int ValidateSystem( AstFrame *this_frame, AstSystemType system, const char *method, int *status ) { -/* -* Name: -* ValidateSystem - -* Purpose: -* Validate a value for a Frame's System attribute. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* int ValidateSystem( AstFrame *this, AstSystemType system, -* const char *method, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astValidateSystem -* method inherited from the Frame class). - -* Description: -* This function checks the validity of the supplied system value. -* If the value is valid, it is returned unchanged. Otherwise, an -* error is reported and a value of AST__BADSYSTEM is returned. - -* Parameters: -* this -* Pointer to the Frame. -* system -* The system value to be checked. -* method -* Pointer to a constant null-terminated character string -* containing the name of the method that invoked this function -* to validate an axis index. This method name is used solely -* for constructing error messages. -* status -* Pointer to the inherited status variable. - -* Returned Value: -* The validated system value. - -* Notes: -* - A value of AST_BADSYSTEM will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*- -*/ - -/* Local Variables: */ - AstSystemType result; /* Validated system value */ - AstFrame *fr; /* Pointer to FrameSet's current Frame */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - -/* Initialise. */ - result = AST__BADSYSTEM; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_frame; - -/* Obtain a pointer to the FrameSet's current Frame and invoke the - astValidateSystem method for this Frame. Annul the Frame pointer - afterwards. */ - fr = astGetFrame( this, AST__CURRENT ); - result = astValidateSystem( this, system, method ); - fr = astAnnul( fr ); - -/* If an error occurred, clear the result value. */ - if ( !astOK ) result = AST__BADSYSTEM; - -/* Return the result. */ - return result; -} - -static void VSet( AstObject *this_object, const char *settings, - char **text, va_list args, int *status ) { -/* -* Name: -* VSet - -* Purpose: -* Set values for a FrameSet's attributes. - -* Type: -* Private function. - -* Synopsis: -* #include "frameset.h" -* void VSet( AstObject *this, const char *settings, char **text, -* va_list args, int *status ) - -* Class Membership: -* FrameSet member function (over-rides the protected astVSet -* method inherited from the Object class). - -* Description: -* This function assigns a set of attribute values for a FrameSet, -* the attributes and their values being specified by means of a -* string containing a comma-separated list of the form: -* -* "attribute1 = value1, attribute2 = value2, ... " -* -* Here, "attribute" specifies an attribute name and the value to -* the right of each "=" sign should be a suitable textual -* representation of the value to be assigned to that -* attribute. This will be interpreted according to the attribute's -* data type. -* -* The string supplied may also contain "printf"-style format -* specifiers identified by a "%" sign in the usual way. If -* present, these will be substituted by values supplied as -* optional arguments (as a va_list variable argument list), using -* the normal "printf" rules, before the string is used. - -* Parameters: -* this -* Pointer to the FrameSet. -* settings -* Pointer to a null-terminated string containing a -* comma-separated list of attribute settings. -* text -* Pointer to a location at which to return a pointer to dynamic -* memory holding a copy of the expanded setting string. This memory -* should be freed using astFree when no longer needed. If a NULL -* pointer is supplied, no string is created. -* args -* The variable argument list which contains values to be -* substituted for any "printf"-style format specifiers that -* appear in the "settings" string. -* status -* Pointer to the inherited status variable. - -* Notes: -* - This function preserves the integrity of the FrameSet (if -* possible) by appropriately remapping its current Frame to take -* account of its changed attribute values. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Declare the thread specific global data */ - AstFrame *save_frame; /* Saved pointer to integrity Frame */ - AstFrameSet *this; /* Pointer to FrameSet structure */ - char *fulltext; /* Pointer to expanded text string */ - const char *save_method; /* Saved pointer to method name */ - int len; /* Length of settings string */ - int ok; /* Status OK? */ - int save_lost; /* Saved integrity modified flag */ - -/* Initialise */ - if( text ) *text = NULL; - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Get a pointer to the structure holding thread-specific global data. */ - astGET_GLOBALS(this_object); - -/* Obtain the length of the "settings" string and test it is not - zero. If it is, there is nothing more to do. */ - len = (int) strlen( settings ); - if ( len != 0 ) { - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* This function may be invoked recursively (because astConvert, - below, constructs a FrameSet and may require that its attributes be - set). To allow this, we first save any existing FrameSet integrity - information in local variables. */ - save_frame = integrity_frame; - save_lost = integrity_lost; - save_method = integrity_method; - -/* Set the name of the method being used (for use in error - messages). */ - integrity_method = "astSet"; - -/* Record the initial integrity state of the FrameSet. */ - RecordIntegrity( this, status ); - -/* Invoke the parent astVSet method to set the FrameSet's attribute - values and note if this succeeds. */ - (*parent_vset)( this_object, settings, &fulltext, args, status ); - ok = astOK; - -/* Restore the FrameSet's integrity. */ - RestoreIntegrity( this, status ); - -/* If integrity could not be restored, then add contextual error - information. */ - if ( !astOK && ok ) { - -/* Display the message. */ - astError( astStatus, "Unable to accommodate the attribute setting " - "\"%s\".", status, fulltext ); - } - -/* Restore any saved FrameSet integrity information. */ - integrity_frame = save_frame; - integrity_lost = save_lost; - integrity_method = save_method; - -/* If the full text of the setting string is not needed, free it. - Otherwise return it. */ - if( text ) { - *text = fulltext; - } else { - fulltext = astFree( fulltext ); - } - } -} - -/* FrameSet Attributes. */ -/* -------------------- */ -/* -*att++ -* Name: -* AllVariants - -* Purpose: -* A list of the variant Mappings associated with the current Frame. - -* Type: -* Public attribute. - -* Synopsis: -* String, read-only. - -* Description: -* This attribute gives a space separated list of the names of all the -* variant Mappings associated with the current Frame (see attribute -* "Variant"). If the current Frame has no variant Mappings, then the -* list will hold a single entry equal to the Domain name of the -* current Frame. - -* Applicability: -* FrameSet -* All FrameSets have this attribute. -*att-- -*/ - -/* -*att++ -* Name: -* Base - -* Purpose: -* FrameSet base Frame index. - -* Type: -* Public attribute. - -* Synopsis: -* Integer. - -* Description: -* This attribute gives the index of the Frame which is to be -* regarded as the "base" Frame within a FrameSet. The default is -* the first Frame added to the FrameSet when it is created (this -* Frame always has an index of 1). -* -* When setting a new value for this attribute, a string may be -* supplied instead of an integer index. In this case a search -* is made within the FrameSet for a Frame that has its Domain -* attribute value equal to the supplied string (the comparison is -* case-insensitive). If found, the Frame is made the base Frame. -* Otherwise an error is reported. - -* Applicability: -* FrameSet -* All FrameSets have this attribute. - -* Notes: -* - Inverting a FrameSet (inverting the boolean sense of its -c Invert attribute, with the astInvert function for example) will -f Invert attribute, with the AST_INVERT routine for example) will -* interchange the values of its Base and Current attributes. -*att-- -*/ - -/* -*att++ -* Name: -* Current - -* Purpose: -* FrameSet current Frame index. - -* Type: -* Public attribute. - -* Synopsis: -* Integer. - -* Description: -* This attribute gives the index of the Frame which is to be -* regarded as the "current" Frame within a FrameSet. The default -* is the most recent Frame added to the FrameSet (this Frame -* always has an index equal to the FrameSet's Nframe attribute). -* -* When setting a new value for this attribute, a string may be -* supplied instead of an integer index. In this case a search -* is made within the FrameSet for a Frame that has its Domain -* attribute value equal to the supplied string (the comparison is -* case-insensitive). If found, the Frame is made the current Frame. -* Otherwise an error is reported. - -* Applicability: -* FrameSet -* All FrameSets have this attribute. - -* Notes: -* - Inverting a FrameSet (inverting the boolean sense of its -c Invert attribute, with the astInvert function for example) will -f Invert attribute, with the AST_INVERT routine for example) will -* interchange the values of its Base and Current attributes. -*att-- -*/ - -/* -*att++ -* Name: -* Nframe - -* Purpose: -* Number of Frames in a FrameSet. - -* Type: -* Public attribute. - -* Synopsis: -* Integer, read-only. - -* Description: -* This attribute gives the number of Frames in a FrameSet. This -* value will change as Frames are added or removed, but will -* always be at least one. - -* Applicability: -* FrameSet -* All FrameSets have this attribute. -*att-- -*/ - -/* -*att++ -* Name: -* Variant - -* Purpose: -* Indicates which variant of the current Frame is to be used. - -* Type: -* Public attribute. - -* Synopsis: -* String. - -* Description: -* This attribute can be used to change the Mapping that connects the -* current Frame to the other Frames in the FrameSet. By default, each -* Frame in a FrameSet is connected to the other Frames by a single -* Mapping that can only be changed by using the -c astRemapFrame -f AST_REMAPFRAME -* method. However, it is also possible to associate multiple Mappings -* with a Frame, each Mapping having an identifying name. If this is -* done, the "Variant" attribute can be set to indicate the name of -* the Mapping that is to be used with the current Frame. -* -* A possible (if unlikely) use-case is to create a FrameSet that can -* be used to describe the WCS of an image formed by co-adding images -* of two different parts of the sky. In such an image, each pixel contains -* flux from two points on the sky.and so the WCS for the image should -* ideally contain one pixel Frame and two SkyFrames - one describing -* each of the two co-added images. There is nothing to prevent a -* FrameSet containing two explicit SkyFrames, but the problem then arises -* of how to distinguish between them. The two primary characteristics of -* a Frame that distinguishes it from other Frames are its class and its -* Domain attribute value. The class of a Frame cannot be changed, but we -* could in principle use two different Domain values to distinguish the -* two SkyFrames. However, in practice it is not uncommon for application -* software to assume that SkyFrames will have the default Domain value -* of "SKY". That is, instead of searching for Frames that have a class -* of "SkyFrame", such software searches for Frames that have a Domain -* of "SKY". To alleviate this problem, it is possible to add a single -* SkyFrame to the FrameSet, but specifying two alternate Mappings to -* use with the SkyFrame. Setting the "Variant" attribute to the name -* of one or the other of these alternate Mappings will cause the -* SkyFrame to be remapped within the FrameSet so that it uses the -* specified Mapping. The same facility can be used with any class of -* Frame, not just SkyFrames. -* -* To use this facility, the Frame should first be added to the -* FrameSet in the usual manner using the -c astAddFrame method. By default, the Mapping supplied to astAddFrame -f AST_ADDFRAME method. By default, the Mapping supplied to AST_ADDVARIANT -* is assigned a name equal to the Domain name of the Frame. To assign a -* different name to it, the -c astAddVariant -f AST_ADDVARIANT -* method should then be called specifying the required name and a NULL -* Mapping. The -c astAddVariant -f AST_ADDVARIANT -* method should then be called repeatedly to add each required extra -* Mapping to the current Frame, supplying a unique name for each one. -* -* Each Frame in a FrameSet can have its own set of variant Mappings. -* To control the Mappings in use with a specific Frame, you need first -* to make it the current Frame in the FrameSet. -* -* The -c astMirrorVariants function -f AST_MIRRORVARIANTS routine -* allows the effects of variant Mappings associated with a nominated -* Frame to be propagated to other Frames in the FrameSet. -* -* Once this has been done, setting a new value for the "Variant" -* attribute of a FrameSet will cause the current Frame in the -* FrameSet to be remapped to use the specified variant Mapping. An -* error will be reported if the current Frame has no variant Mapping -* with the supplied name. -* -* Getting the value of the "Variant" attribute will return the name -* of the variant Mapping currently in use with the current Frame. If -* the Frame has no variant Mappings, the value will default to the -* Domain name of the current Frame. -* -* Clearing the "Variant" attribute will have the effect of removing -* all variant Mappings (except for the currently selected Mapping) from -* the current Frame. -* -* Testing the "Variant" attribute will return -c a non-zero value -f .TRUE. -* if the current Frame contains any variant Mappings, and -c zero -f .FALSE. -* otherwise. -* -* A complete list of the names associated with all the available -* variant Mappings in the current Frame can be obtained from the -* AllVariants attribute. -* -* If a Frame with variant Mappings is remapped using the -c astRemapFrame -f AST_REMAPFRAME -* method, the currently selected variant Mapping is used by -c astRemapFrame -f AST_REMAPFRAME -* and the other variant Mappings are removed from the Frame. - -* Applicability: -* FrameSet -* All FrameSets have this attribute. -*att-- -*/ - -/* Access to attributes of the current Frame. */ -/* ------------------------------------------ */ -/* Use the macros defined at the start of this file to implement - private member functions that give access to the attributes of the - current Frame of a FrameSet and its axes. These functions over-ride - the attribute access methods inherited from the Frame class. */ - -/* Clear, Get, Set and Test axis-independent Frame attributes. */ -MAKE_CLEAR(Digits) -MAKE_CLEAR(Domain) -MAKE_CLEAR(MatchEnd) -MAKE_CLEAR(MaxAxes) -MAKE_CLEAR(MinAxes) -MAKE_CLEAR(Permute) -MAKE_CLEAR(PreserveAxes) -MAKE_CLEAR(Title) - -MAKE_GET(Digits,int) -MAKE_GET(Domain,const char *) -MAKE_GET(MatchEnd,int) -MAKE_GET(MaxAxes,int) -MAKE_GET(MinAxes,int) -MAKE_GET(Permute,int) -MAKE_GET(PreserveAxes,int) -MAKE_GET(Title,const char *) -MAKE_SET(Digits,int) -MAKE_SET(Domain,const char *) -MAKE_SET(MatchEnd,int) -MAKE_SET(MaxAxes,int) -MAKE_SET(MinAxes,int) -MAKE_SET(Permute,int) -MAKE_SET(PreserveAxes,int) -MAKE_SET(Title,const char *) -MAKE_TEST(Digits) -MAKE_TEST(Domain) -MAKE_TEST(MatchEnd) -MAKE_TEST(MaxAxes) -MAKE_TEST(MinAxes) -MAKE_TEST(Permute) -MAKE_TEST(PreserveAxes) -MAKE_TEST(Title) - -MAKE_GET(ActiveUnit,int) -MAKE_SET(ActiveUnit,int) -MAKE_TEST(ActiveUnit) - -MAKE_GET(System,AstSystemType) -MAKE_SET(System,AstSystemType) -MAKE_TEST(System) -MAKE_CLEAR(System) - -MAKE_GET(AlignSystem,AstSystemType) -MAKE_SET(AlignSystem,AstSystemType) -MAKE_TEST(AlignSystem) -MAKE_CLEAR(AlignSystem) - -MAKE_GET(Epoch,double) -MAKE_SET(Epoch,double) -MAKE_TEST(Epoch) -MAKE_CLEAR(Epoch) - -MAKE_GET(Dtai,double) -MAKE_SET(Dtai,double) -MAKE_TEST(Dtai) -MAKE_CLEAR(Dtai) - -MAKE_GET(Dut1,double) -MAKE_SET(Dut1,double) -MAKE_TEST(Dut1) -MAKE_CLEAR(Dut1) - -MAKE_GET(ObsLon,double) -MAKE_SET(ObsLon,double) -MAKE_TEST(ObsLon) -MAKE_CLEAR(ObsLon) - -MAKE_GET(ObsLat,double) -MAKE_SET(ObsLat,double) -MAKE_TEST(ObsLat) -MAKE_CLEAR(ObsLat) - -MAKE_GET(ObsAlt,double) -MAKE_SET(ObsAlt,double) -MAKE_TEST(ObsAlt) -MAKE_CLEAR(ObsAlt) - -/* Clear, Get, Set and Test axis-dependent Frame attributes. */ -MAKE_CLEAR_AXIS(Direction) -MAKE_CLEAR_AXIS(Format) -MAKE_CLEAR_AXIS(Label) -MAKE_CLEAR_AXIS(Symbol) -MAKE_CLEAR_AXIS(Unit) -MAKE_GET_AXIS(Direction,int) -MAKE_GET_AXIS(Format,const char *) -MAKE_GET_AXIS(Label,const char *) -MAKE_GET_AXIS(Symbol,const char *) -MAKE_GET_AXIS(Unit,const char *) -MAKE_SET_AXIS(Direction,int) -MAKE_SET_AXIS(Format,const char *) -MAKE_SET_AXIS(Label,const char *) -MAKE_SET_AXIS(Symbol,const char *) -MAKE_SET_AXIS(Unit,const char *) -MAKE_TEST_AXIS(Direction) -MAKE_TEST_AXIS(Format) -MAKE_TEST_AXIS(Label) -MAKE_TEST_AXIS(Symbol) -MAKE_TEST_AXIS(Unit) - -MAKE_GET_AXIS(Bottom,double) -MAKE_SET_AXIS(Bottom,double) -MAKE_TEST_AXIS(Bottom) -MAKE_CLEAR_AXIS(Bottom) - -MAKE_GET_AXIS(Top,double) -MAKE_SET_AXIS(Top,double) -MAKE_TEST_AXIS(Top) -MAKE_CLEAR_AXIS(Top) - -/* Copy constructor. */ -/* ----------------- */ -static void Copy( const AstObject *objin, AstObject *objout, int *status ) { -/* -* Name: -* Copy - -* Purpose: -* Copy constructor for FrameSet objects. - -* Type: -* Private function. - -* Synopsis: -* void Copy( const AstObject *objin, AstObject *objout, int *status ) - -* Description: -* This function implements the copy constructor for FrameSet 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: */ - AstFrameSet *in; /* Pointer to input FrameSet */ - AstFrameSet *out; /* Pointer to output FrameSet */ - int iframe; /* Loop counter for Frames */ - int inode; /* Loop counter for nodes */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain pointers to the input and output FrameSets. */ - in = (AstFrameSet *) objin; - out = (AstFrameSet *) objout; - -/* For safety, first clear any references to the input memory from - the output FrameSet. */ - out->frame = NULL; - out->varfrm = NULL; - out->node = NULL; - out->map = NULL; - out->link = NULL; - out->invert = NULL; - -/* Allocate memory in the output FrameSet to store the Frame and node - information and copy scalar information across. */ - out->frame = astMalloc( sizeof( AstFrame * ) * (size_t) in->nframe ); - out->varfrm = astStore( NULL, in->varfrm, sizeof( int ) * - (size_t) in->nframe ); - out->node = astStore( NULL, in->node, sizeof( int ) * - (size_t) in->nframe ); - out->map = astMalloc( sizeof( AstMapping * ) * (size_t) ( in->nnode - 1 ) ); - out->link = astStore( NULL, in->link, sizeof( int ) * - (size_t) ( in->nnode - 1 ) ); - out->invert = astStore( NULL, in->invert, sizeof( int ) * - (size_t) ( in->nnode - 1 ) ); - -/* If OK, make copies of each input Frame and Mapping and store the - resulting pointers in the output FrameSet. */ - if ( astOK ) { - for ( iframe = 0; iframe < in->nframe; iframe++ ) { - out->frame[ iframe ] = astCopy( in->frame[ iframe ] ); - } - for ( inode = 0; inode < in->nnode - 1; inode++ ) { - out->map[ inode ] = astCopy( in->map[ inode ] ); - } - -/* If an error occurred while copying any of these objects, clean up - by looping through the arrays of pointers again and annulling them - all. */ - if ( !astOK ) { - for ( iframe = 0; iframe < in->nframe; iframe++ ) { - out->frame[ iframe ] = astAnnul( out->frame[ iframe ] ); - } - for ( inode = 0; inode < in->nnode - 1; inode++ ) { - out->map[ inode ] = astAnnul( out->map[ inode ] ); - } - } - } - -/* If an error occurred, clean up by freeing all memory allocated above. */ - if ( !astOK ) { - out->frame = astFree( out->frame ); - out->varfrm = astFree( out->varfrm ); - out->node = astFree( out->node ); - out->map = astFree( out->map ); - out->link = astFree( out->link ); - out->invert = astFree( out->invert ); - } -} - -/* Destructor. */ -/* ----------- */ -static void Delete( AstObject *obj, int *status ) { -/* -* Name: -* Delete - -* Purpose: -* Destructor for FrameSet objects. - -* Type: -* Private function. - -* Synopsis: -* void Delete( AstObject *obj, int *status ) - -* Description: -* This function implements the destructor for FrameSet 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: */ - AstFrameSet *this; /* Pointer to FrameSet */ - int iframe; /* Loop counter for Frames */ - int inode; /* Loop counter for nodes */ - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) obj; - -/* Annul all Frame pointers and clear the node numbers associated with - them. */ - for ( iframe = 0; iframe < this->nframe; iframe++ ) { - this->frame[ iframe ] = astAnnul( this->frame[ iframe ] ); - this->node[ iframe ] = 0; - } - -/* Annul all Mapping pointers and clear the links between pairs of - nodes and the associated Mapping Invert information. */ - for ( inode = 0; inode < this->nnode - 1; inode++ ) { - this->map[ inode ] = astAnnul( this->map[ inode ] ); - this->link[ inode ] = 0; - this->invert[ inode ] = 0; - } - -/* Free all allocated memory. */ - this->frame = astFree( this->frame ); - this->varfrm = astFree( this->varfrm ); - this->node = astFree( this->node ); - this->map = astFree( this->map ); - this->link = astFree( this->link ); - this->invert = astFree( this->invert ); -} - -/* Dump function. */ -/* -------------- */ -static void Dump( AstObject *this_object, AstChannel *channel, int *status ) { -/* -* Name: -* Dump - -* Purpose: -* Dump function for FrameSet 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 FrameSet class to an output Channel. - -* Parameters: -* this -* Pointer to the FrameSet 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: */ - AstFrameSet *this; /* Pointer to the FrameSet structure */ - char comment[ COMMENT_LEN + 1 ]; /* Buffer for comment string */ - char key[ KEY_LEN + 1 ]; /* Buffer for keyword string */ - int ifr; /* Loop counter for Frames */ - int inode; /* Loop counter for nodes */ - int invert; /* Invert attribute value */ - int ival; /* Integer value */ - int set; /* Attribute value set? */ - -/* Check the global error status. */ - if ( !astOK ) return; - -/* Obtain a pointer to the FrameSet structure. */ - this = (AstFrameSet *) this_object; - -/* Determine if the FrameSet is inverted. This is required so that the - effects of inversion can be un-done to obtain information about the - "true" Base and Current Frames. (The values written are "internal" - values that are not affected by the Invert setting.) */ - invert = astGetInvert( this ); - -/* Write out values representing the instance variables for the - FrameSet 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. */ - -/* Nframe. */ -/* ------- */ - set = ( this->nframe != 0 ); - ival = set ? this->nframe : astGetNframe( this ); - astWriteInt( channel, "Nframe", set, 1, ival, - "Number of Frames in FrameSet" ); - -/* Base. */ -/* ----- */ - set = ( this->base != -INT_MAX ); - ival = set ? this->base : ( !invert ? astGetBase( this ) : - astGetCurrent( this ) ); - astWriteInt( channel, "Base", set, 1, ival, "Index of base Frame" ); - -/* Current. */ -/* -------- */ - set = ( this->current != -INT_MAX ); - ival = set ? this->current : ( !invert ? astGetCurrent( this ) : - astGetBase( this ) ); - astWriteInt( channel, "Currnt", set, 1, ival, "Index of current Frame" ); - -/* Number of nodes. */ -/* ---------------- */ - ival = this->nnode; - set = ( ival != this->nframe ); - astWriteInt( channel, "Nnode", set, 0, ival, - "Number of nodes in FrameSet" ); - -/* Node index for each Frame. */ -/* -------------------------- */ -/* There is a node value for each Frame in the FrameSet. */ - for ( ifr = 1; ifr <= this->nframe; ifr++ ) { - -/* Convert node numbering to start at 1 for the external - representation. Regard a node number as "set" if it differs from - the Frame number. */ - ival = this->node[ ifr - 1 ] + 1; - set = ( ival != ifr ); - -/* Create a suitable keyword and comment. */ - (void) sprintf( key, "Nod%d", ifr ); - (void) sprintf( comment, - "Frame %d is associated with node %d", ifr, ival ); - -/* Write out the value. */ - astWriteInt( channel, key, set, 0, ival, comment ); - } - -/* Index of variants Frame for each Frame. */ -/* --------------------------------------- */ - for ( ifr = 1; ifr <= this->nframe; ifr++ ) { - -/* Retain the one-based Frame index values in varfrm. Regard a number as - "set" if it is greater than zero. */ - ival = this->varfrm[ ifr - 1 ]; - set = ( ival > 0 ); - -/* Create a suitable keyword and comment. */ - (void) sprintf( key, "VFr%d", ifr ); - (void) sprintf( comment, - "Frame %d inherits variants from Frame %d", ifr, ival ); - -/* Write out the value. */ - astWriteInt( channel, key, set, 0, ival, comment ); - } - -/* Links between nodes. */ -/* -------------------- */ -/* Each node in the FrameSet (except the first) has a link to another - node from which it is derived. */ - for ( inode = 1; inode < this->nnode; inode++ ) { - -/* Convert node numbering to start at 1 (as above). */ - ival = this->link[ inode - 1 ] + 1; - (void) sprintf( key, "Lnk%d", inode + 1 ); - (void) sprintf( comment, - "Node %d is derived from node %d", inode + 1, ival ); - astWriteInt( channel, key, 1, 0, ival, comment ); - -/* Inversion flags. */ -/* ---------------- */ -/* Each node with a link has a value which the Invert attribute of the - associated Mapping should have when the transformation from the - parent node to the node in question is required. */ - ival = this->invert[ inode - 1 ]; - -/* Regard the value as set only if the Mapping's inverse - transformation is required. */ - set = ( ival != 0 ); - (void) sprintf( key, "Inv%d", inode + 1 ); - astWriteInt( channel, key, set, 0, ival, - ival ? "The inverse mapping is used" : - "The forward mapping is used" ); - } - -/* Frame objects. */ -/* -------------- */ -/* Output an Object description for each Frame in the FrameSet. */ - for ( ifr = 1; ifr <= this->nframe; ifr++ ) { - (void) sprintf( key, "Frm%d", ifr ); - (void) sprintf( comment, "Frame number %d", ifr ); - astWriteObject( channel, key, 1, 1, this->frame[ ifr - 1 ], - comment ); - } - -/* Mapping objects. */ -/* ---------------- */ -/* Output an Object description for each Mapping in the FrameSet. */ - for ( inode = 1; inode < this->nnode; inode++ ) { - (void) sprintf( key, "Map%d", inode + 1 ); - (void) sprintf( comment, "Mapping between nodes %d and %d", - this->link[ inode - 1 ] + 1, inode + 1 ); - astWriteObject( channel, key, 1, 1, this->map[ inode - 1 ], comment ); - } - -/* Undefine macros local to this function. */ -#undef COMMENT_LEN -#undef KEY_LEN -} - -/* Standard class functions. */ -/* ========================= */ -/* Implement the astIsAFrameSet and astCheckFrameSet functions using - the macros defined for this purpose in the "object.h" header - file. */ -astMAKE_ISA(FrameSet,Frame) -astMAKE_CHECK(FrameSet) - -AstFrameSet *astFrameSet_( void *frame_void, const char *options, int *status, ...) { -/* -*+ -* Name: -* astFrameSet - -* Purpose: -* Create a FrameSet. - -* Type: -* Protected function. - -* Synopsis: -* #include "frameset.h" -* AstFrameSet *astFrameSet( AstFrame *frame, const char *options, int *status, ... ) - -* Class Membership: -* FrameSet constructor. - -* Description: -* This function creates a new FrameSet and optionally initialises -* its attributes. - -* Parameters: -* frame -* Pointer to the initial Frame. If this is not a FrameSet, the -* new FrameSet will be initialised to contain this Frame alone. -* -* If it is a FrameSet, the new FrameSet will be initialised to -* contain the same Frames (and Mappings) and to have the same -* attribute values as the one supplied. This is similar to -* making a copy, except that the Frames (and Mappings) -* contained in the original FrameSet are not themselves copied, -* but are shared by both FrameSets. -* options -* Pointer to a null terminated string containing an optional -* comma-separated list of attribute assignments to be used for -* initialising the new FrameSet. 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 FrameSet. - -* Notes: -* - A NULL pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*- - -* Implementation Notes: -* - This function implements the basic FrameSet constructor which -* is available via the protected interface to the FrameSet class. -* A public interface is provided by the astFrameSetId_ function. -* - Because this function has a variable argument list, it is -* invoked by a macro that evaluates to a function pointer (not a -* function invocation) and no checking or casting of arguments is -* performed before the function is invoked. Because of this, the -* "frame" parameter is of type (void *) and is converted and -* validated within the function itself. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Pointer to thread-specific global data */ - AstFrame *frame; /* Pointer to Frame structure */ - AstFrameSet *new; /* Pointer to new FrameSet */ - va_list args; /* Variable argument list */ - -/* Initialise. */ - new = NULL; - -/* Get a pointer to the thread specific global data structure. */ - astGET_GLOBALS(NULL); - -/* Check the global status. */ - if ( !astOK ) return new; - -/* Obtain and validate a pointer to the Frame structure provided. */ - frame = astCheckFrame( frame_void ); - if ( astOK ) { - -/* Initialise the FrameSet, allocating memory and initialising the - virtual function table as well if necessary. */ - new = astInitFrameSet( NULL, sizeof( AstFrameSet ), !class_init, - &class_vtab, "FrameSet", frame ); - -/* 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 - FrameSet'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 FrameSet. */ - return new; -} - -AstFrameSet *astInitFrameSet_( void *mem, size_t size, int init, - AstFrameSetVtab *vtab, const char *name, - AstFrame *frame, int *status ) { -/* -*+ -* Name: -* astInitFrameSet - -* Purpose: -* Initialise a FrameSet. - -* Type: -* Protected function. - -* Synopsis: -* #include "frameset.h" -* AstFrameSet *astInitFrameSet( void *mem, size_t size, int init, -* AstFrameSetVtab *vtab, const char *name, -* AstFrame *frame ) - -* Class Membership: -* FrameSet initialiser. - -* Description: -* This function is provided for use by class implementations to -* initialise a new FrameSet object. It allocates memory (if -* necessary) to accommodate the FrameSet plus any additional data -* associated with the derived class. It then initialises a -* FrameSet 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 FrameSet at the start of the memory passed -* via the "vtab" parameter. - -* Parameters: -* mem -* A pointer to the memory in which the FrameSet is to be -* created. This must be of sufficient size to accommodate the -* FrameSet data (sizeof(FrameSet)) 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 FrameSet (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 FrameSet structure, so a valid value must be -* supplied even if not required for allocating memory. -* init -* A logical flag indicating if the FrameSet'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 FrameSet. -* name -* Pointer to a constant null-terminated character string which -* contains the name of the class to which the new object -* belongs (it is this pointer value that will subsequently be -* returned by the astGetClass method). -* frame -* Pointer to the initial Frame (or FrameSet). - -* Returned Value: -* A pointer to the new FrameSet. - -* Notes: -* - A null pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*- -*/ - -/* Local Variables: */ - AstFrameSet *new; /* Pointer to new FrameSet */ - AstFrameSet *old; /* Pointer to original FrameSet */ - int iframe; /* Loop counter for Frames */ - int inode; /* Loop counter for nodes */ - -/* Check the global status. */ - if ( !astOK ) return NULL; - -/* If necessary, initialise the virtual function table. */ - if ( init ) astInitFrameSetVtab( vtab, name ); - -/* Initialise a Frame structure (the parent class) as the first - component within the FrameSet structure, allocating memory if - necessary. Give this Frame zero axes, as all axis information for - the FrameSet will be derived from the Frames it contains. */ - new = (AstFrameSet *) astInitFrame( mem, size, 0, - (AstFrameVtab *) vtab, name, 0 ); - - if ( astOK ) { - -/* Initialise the FrameSet data. */ -/* ----------------------------- */ - -/* Normal Frame supplied. */ -/* ---------------------- */ -/* Check that the Frame supplied is not a FrameSet (initialising using - a FrameSet is a special case which is handled below). If not, we - initialise the new FrameSet to refer to a single Frame. */ - if ( !astIsAFrameSet( frame ) && astOK ) { - -/* Allocate memory for the arrays of Frame information. */ - new->frame = astMalloc( sizeof( AstFrame * ) ); - new->node = astMalloc( sizeof( int ) ); - new->varfrm = astMalloc( sizeof( int ) ); - -/* The node arrays are not required until at least two Frames are - present. */ - new->map = NULL; - new->link = NULL; - new->invert = NULL; - -/* If OK, initialise these arrays, thus adding the Frame to the - FrameSet. */ - if ( astOK ) { - new->frame[ 0 ] = astClone( frame ); - new->node[ 0 ] = 0; - new->varfrm[ 0 ] = 0; - new->nframe = 1; - new->nnode = 1; - -/* Initialise the FrameSet attributes to their undefined states. */ - new->base = -INT_MAX; - new->current = -INT_MAX; - } - -/* FrameSet supplied. */ -/* ------------------ */ -/* If a FrameSet was supplied, we will initialise the new FrameSet to - refer to the same Frame and Mapping information (this is similar to - making a copy, except that we clone all the pointers, instead of - copying the Objects they refer to). */ - } else if ( astOK ) { - -/* Obtain a pointer to the original FrameSet structure. */ - old = (AstFrameSet *) frame; - -/* Allocate memory in the new FrameSet to store the Frame and node - information and copy any scalar information across. */ - new->frame = astMalloc( sizeof( AstFrame * ) * (size_t) old->nframe ); - new->node = astStore( NULL, old->node, - sizeof( int ) * (size_t) old->nframe ); - new->varfrm = astStore( NULL, old->varfrm, - sizeof( int ) * (size_t) old->nframe ); - new->map = astMalloc( sizeof( AstMapping * ) * - (size_t) ( old->nnode - 1 ) ); - new->link = astStore( NULL, old->link, - sizeof( int ) * (size_t) ( old->nnode - 1 ) ); - new->invert = astStore( NULL, old->invert, - sizeof( int ) * (size_t) ( old->nnode - 1 ) ); - -/* If OK, clone the pointer to each Frame and Mapping referenced by - the original FrameSet and store the resulting pointers in the new - FrameSet. */ - if ( astOK ) { - for ( iframe = 0; iframe < old->nframe; iframe++ ) { - new->frame[ iframe ] = astClone( old->frame[ iframe ] ); - } - for ( inode = 0; inode < old->nnode - 1; inode++ ) { - new->map[ inode ] = astClone( old->map[ inode ] ); - } - -/* If an error occurred while cloning any of these pointers, clean up - by looping through the arrays of cloned pointers again and - annulling them all. */ - if ( !astOK ) { - for ( iframe = 0; iframe < old->nframe; iframe++ ) { - new->frame[ iframe ] = astAnnul( new->frame[ iframe ] ); - } - for ( inode = 0; inode < old->nnode - 1; inode++ ) { - new->map[ inode ] = astAnnul( new->map[ inode ] ); - } - } - } - -/* If an error occurred, clean up by freeing all memory allocated - above. */ - if ( !astOK ) { - new->frame = astFree( new->frame ); - new->node = astFree( new->node ); - new->varfrm = astFree( new->varfrm ); - new->map = astFree( new->map ); - new->link = astFree( new->link ); - new->invert = astFree( new->invert ); - } - -/* Copy the Frame and node counts across. */ - new->nframe = old->nframe; - new->nnode = old->nnode; - -/* Copy the other FrameSet attributes across. */ - new->base = old->base; - new->current = old->current; - -/* Transfer any other inherited attribute values that relate to the - FrameSet itself (rather than the enclosed Frames). */ - if ( astTestInvert( old ) ) astSetInvert( new, astGetInvert( old ) ); - } - -/* 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; - -/* Undefine macros local to this function. */ -#undef TRANSFER -} - -AstFrameSet *astLoadFrameSet_( void *mem, size_t size, - AstFrameSetVtab *vtab, const char *name, - AstChannel *channel, int *status ) { -/* -*+ -* Name: -* astLoadFrameSet - -* Purpose: -* Load a FrameSet. - -* Type: -* Protected function. - -* Synopsis: -* #include "frameset.h" -* AstFrameSet *astLoadFrameSet( void *mem, size_t size, -* AstFrameSetVtab *vtab, const char *name, -* AstChannel *channel ) - -* Class Membership: -* FrameSet loader. - -* Description: -* This function is provided to load a new FrameSet 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 -* FrameSet structure in this memory, using data read from the -* input Channel. - -* Parameters: -* mem -* A pointer to the memory into which the FrameSet is to be -* loaded. This must be of sufficient size to accommodate the -* FrameSet data (sizeof(FrameSet)) 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 FrameSet (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 FrameSet 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(AstFrameSet) is used instead. -* vtab -* Pointer to the start of the virtual function table to be -* associated with the new FrameSet. If this is NULL, a pointer -* to the (static) virtual function table for the FrameSet 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 "FrameSet" is used instead. - -* Returned Value: -* A pointer to the new FrameSet. - -* Notes: -* - A null pointer will be returned if this function is invoked -* with the global error status set, or if it should fail for any -* reason. -*- -*/ - -/* Local Constants: */ - astDECLARE_GLOBALS /* Pointer to thread-specific global data */ -#define KEY_LEN 50 /* Maximum length of a keyword */ - -/* Local Variables: */ - AstFrameSet *new; /* Pointer to the new FrameSet */ - char key[ KEY_LEN + 1 ]; /* Buffer for keyword string */ - int ifr; /* Get a pointer to the thread specific global data structure. */ - -/* Loop counter for Frames */ - int inode; /* Loop counter for nodes */ - - 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 FrameSet. In this case the - FrameSet belongs to this class, so supply appropriate values to be - passed to the parent class loader (and its parent, etc.). */ - if ( !vtab ) { - size = sizeof( AstFrameSet ); - vtab = &class_vtab; - name = "FrameSet"; - -/* If required, initialise the virtual function table for this class. */ - if ( !class_init ) { - astInitFrameSetVtab( 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 FrameSet. */ - new = astLoadFrame( mem, size, (AstFrameVtab *) vtab, name, - channel ); - - if ( astOK ) { - -/* Read input data. */ -/* ================ */ -/* Request the input Channel to read all the input data appropriate to - this class into the internal "values list". */ - astReadClassData( channel, "FrameSet" ); - -/* 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. */ - -/* Nframe. */ -/* ------- */ - new->nframe = astReadInt( channel, "nframe", 1 ); - if ( new->nframe < 0 ) new->nframe = 1; - -/* Number of nodes. */ -/* ---------------- */ - new->nnode = astReadInt( channel, "nnode", new->nframe ); - if ( new->nnode < 1 ) new->nnode = 1; - -/* Allocate memory to hold Frame and node information. */ - new->frame = astMalloc( sizeof( AstFrame *) * (size_t) new->nframe ); - new->node = astMalloc( sizeof( int ) * (size_t) new->nframe ); - new->varfrm = astMalloc( sizeof( int ) * (size_t) new->nframe ); - new->link = astMalloc( sizeof( int ) * (size_t) ( new->nnode - 1 ) ); - new->invert = astMalloc( sizeof( int ) * (size_t) ( new->nnode - 1 ) ); - new->map = astMalloc( sizeof( AstMapping * ) * - (size_t) ( new->nnode - 1 ) ); - -/* If an error occurs, ensure that all allocated memory is freed. */ - if ( !astOK ) { - new->frame = astFree( new->frame ); - new->node = astFree( new->node ); - new->varfrm = astFree( new->varfrm ); - new->link = astFree( new->link ); - new->invert = astFree( new->invert ); - new->map = astFree( new->map ); - -/* Otherwise, initialise the arrays which will hold Object pointers. */ - } else { - for ( ifr = 1; ifr <= new->nframe; ifr++ ) { - new->frame[ ifr - 1 ] = NULL; - } - for ( inode = 1; inode < new->nnode; inode++ ) { - new->map[ inode - 1 ] = NULL; - } - -/* Read Frame data... */ - for ( ifr = 1; ifr <= new->nframe; ifr++ ) { - -/* Frame objects. */ -/* -------------- */ -/* Create the required keyword and then read the Frame. */ - (void) sprintf( key, "frm%d", ifr ); - new->frame[ ifr - 1 ] = astReadObject( channel, key, NULL ); - -/* Node index for each Frame. */ -/* -------------------------- */ - (void) sprintf( key, "nod%d", ifr ); - new->node[ ifr - 1 ] = astReadInt( channel, key, ifr ) - 1; - -/* Index of variants Frame. */ -/* ------------------------ */ - (void) sprintf( key, "vfr%d", ifr ); - new->varfrm[ ifr - 1 ] = astReadInt( channel, key, 0 ); - } - -/* Read node data... */ - for ( inode = 1; inode < new->nnode; inode++ ) { - -/* Links between nodes. */ -/* -------------------- */ - (void) sprintf( key, "lnk%d", inode + 1 ); - new->link[ inode - 1 ] = astReadInt( channel, key, 0 ) - 1; - -/* Inversion flags. */ -/* ---------------- */ - (void) sprintf( key, "inv%d", inode + 1 ); - new->invert[ inode - 1 ] = astReadInt( channel, key, 0 ); - -/* Mapping objects. */ -/* ---------------- */ - (void) sprintf( key, "map%d", inode + 1 ); - new->map[ inode - 1 ] = astReadObject( channel, key, NULL ); - } - -/* Read remaining data... */ - -/* Base. */ -/* ----- */ - new->base = astReadInt( channel, "base", -INT_MAX ); - if ( new->base < 1 ) new->base = -INT_MAX; - -/* Current. */ -/* -------- */ - new->current = astReadInt( channel, "currnt", -INT_MAX ); - if ( new->base < 1 ) new->base = -INT_MAX; - } - -/* If an error occurred, clean up by deleting the new FrameSet. */ - if ( !astOK ) new = astDelete( new ); - } - -/* Return the new FrameSet pointer. */ - return new; - -/* Undefine macros local to this function. */ -#undef KEY_LEN -} - -/* Virtual function interfaces. */ -/* ============================ */ -/* These provide the external interface to the virtual functions defined by - this class. Each simply checks the global error status and then locates and - executes the appropriate member function, using the function pointer stored - in the object's virtual function table (this pointer is located using the - astMEMBER macro defined in "object.h"). - - Note that the member function may not be the one defined here, as it may - have been over-ridden by a derived class. However, it should still have the - same interface. */ -void astAddFrame_( AstFrameSet *this, int iframe, AstMapping *map, - AstFrame *frame, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,AddFrame))( this, iframe, map, frame, status ); -} -void astClearBase_( AstFrameSet *this, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,ClearBase))( this, status ); -} -void astClearCurrent_( AstFrameSet *this, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,ClearCurrent))( this, status ); -} -void astClearVariant_( AstFrameSet *this, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,ClearVariant))( this, status ); -} -int astGetBase_( AstFrameSet *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,FrameSet,GetBase))( this, status ); -} -int astGetCurrent_( AstFrameSet *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,FrameSet,GetCurrent))( this, status ); -} -const char *astGetVariant_( AstFrameSet *this, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,FrameSet,GetVariant))( this, status ); -} -AstFrame *astGetFrame_( AstFrameSet *this, int iframe, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,FrameSet,GetFrame))( this, iframe, status ); -} -AstMapping *astGetMapping_( AstFrameSet *this, int iframe1, int iframe2, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,FrameSet,GetMapping))( this, iframe1, iframe2, status ); -} -int astGetNframe_( AstFrameSet *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,FrameSet,GetNframe))( this, status ); -} -void astRemapFrame_( AstFrameSet *this, int iframe, AstMapping *map, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,RemapFrame))( this, iframe, map, status ); -} -void astAddVariant_( AstFrameSet *this, AstMapping *map, const char *name, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,AddVariant))( this, map, name, status ); -} -void astMirrorVariants_( AstFrameSet *this, int iframe, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,MirrorVariants))( this, iframe, status ); -} -void astRemoveFrame_( AstFrameSet *this, int iframe, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,RemoveFrame))( this, iframe, status ); -} -void astSetBase_( AstFrameSet *this, int ibase, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,SetBase))( this, ibase, status ); -} -void astSetCurrent_( AstFrameSet *this, int icurrent, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,SetCurrent))( this, icurrent, status ); -} -void astSetVariant_( AstFrameSet *this, const char *variant, int *status ) { - if ( !astOK ) return; - (**astMEMBER(this,FrameSet,SetVariant))( this, variant, status ); -} -int astTestBase_( AstFrameSet *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,FrameSet,TestBase))( this, status ); -} -int astTestCurrent_( AstFrameSet *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,FrameSet,TestCurrent))( this, status ); -} -int astTestVariant_( AstFrameSet *this, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,FrameSet,TestVariant))( this, status ); -} -int astValidateFrameIndex_( AstFrameSet *this, int iframe, - const char *method, int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,FrameSet,ValidateFrameIndex))( this, iframe, - method, status ); -} -const char *astGetAllVariants_( AstFrameSet *this, int *status ) { - if ( !astOK ) return NULL; - return (**astMEMBER(this,FrameSet,GetAllVariants))( this, status ); -} -int astGetNode_( AstFrameSet *this, int inode, int *nnodes, - int *iframe, AstMapping **map, int *parent, - int *status ) { - if ( !astOK ) return 0; - return (**astMEMBER(this,FrameSet,GetNode))( this, inode, nnodes, - iframe, map, parent, 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. */ -AstFrameSet *astFrameSetId_( void *, const char *, ... ); -int astGetNodeId_( AstFrameSet *, int, int *, int *, AstMapping **, int *, int *); - -/* Special interface function implementations. */ -/* ------------------------------------------- */ -AstFrameSet *astFrameSetId_( void *frame_void, const char *options, ... ) { -/* -*++ -* Name: -c astFrameSet -f AST_FRAMESET - -* Purpose: -* Create a FrameSet. - -* Type: -* Public function. - -* Synopsis: -c #include "frameset.h" -c AstFrameSet *astFrameSet( AstFrame *frame, const char *options, ... ) -f RESULT = AST_FRAMESET( FRAME, OPTIONS, STATUS ) - -* Class Membership: -* FrameSet constructor. - -* Description: -* This function creates a new FrameSet and optionally initialises -* its attributes. -* -* A FrameSet consists of a set of one or more Frames (which -* describe coordinate systems), connected together by Mappings -* (which describe how the coordinate systems are inter-related). A -* FrameSet makes it possible to obtain a Mapping between any pair -* of these Frames (i.e. to convert between any of the coordinate -* systems which it describes). The individual Frames are -* identified within the FrameSet by an integer index, with Frames -* being numbered consecutively from one as they are added to the -* FrameSet. -* -* Every FrameSet has a "base" Frame and a "current" Frame (which -* are allowed to be the same). Any of the Frames may be nominated -* to hold these positions, and the choice is determined by the -* values of the FrameSet's Base and Current attributes, which hold -* the indices of the relevant Frames. By default, the first Frame -* added to a FrameSet is its base Frame, and the last one added is -* its current Frame. -* -* The base Frame describes the "native" coordinate system of -* whatever the FrameSet is used to calibrate (e.g. the pixel -* coordinates of an image) and the current Frame describes the -* "apparent" coordinate system in which it should be viewed -* (e.g. displayed, etc.). Any further Frames represent a library -* of alternative coordinate systems, which may be selected by -* making them current. -* -* When a FrameSet is used in a context that requires a Frame, -* (e.g. obtaining its Title value, or number of axes), the current -* Frame is used. A FrameSet may therefore be used in place of its -* current Frame in most situations. -* -* When a FrameSet is used in a context that requires a Mapping, -* the Mapping used is the one between its base Frame and its -* current Frame. Thus, a FrameSet may be used to convert "native" -* coordinates into "apparent" ones, and vice versa. Like any -c Mapping, a FrameSet may also be inverted (see astInvert), which -f Mapping, a FrameSet may also be inverted (see AST_INVERT), which -* has the effect of interchanging its base and current Frames and -* hence of reversing the Mapping between them. -* -* Regions may be added into a FrameSet (since a Region is a type of -* Frame), either explicitly or as components within CmpFrames. In this -* case the Mapping between a pair of Frames within a FrameSet will -* include the effects of the clipping produced by any Regions included -* in the path between the Frames. - -* Parameters: -c frame -f FRAME = INTEGER (Given) -* Pointer to the first Frame to be inserted into the -* FrameSet. This initially becomes both the base and the -* current Frame. (Further Frames may be added using the -c astAddFrame function.) -f AST_ADDFRAME routine.) -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 FrameSet. 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 FrameSet. 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 astFrameSet() -f AST_FRAMESET -* A pointer to the new FrameSet. - -* Notes: -c - If a pointer to an existing FrameSet is given for the "frame" -c parameter, then the new FrameSet will (as a special case) be -f - If a pointer to an existing FrameSet is given for the FRAME -f argument, then the new FrameSet will (as a special case) be -* initialised to contain the same Frames and Mappings, and to have -* the same attribute values, as the one supplied. This process is -c similar to making a copy of a FrameSet (see astCopy), except -f similar to making a copy of a FrameSet (see AST_COPY), except -* that the Frames and Mappings contained in the original are not -* themselves copied, but are shared by both FrameSets. -* - 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 astFrameSet constructor function. It returns an ID value -* (instead of a true C pointer) to external users, and must be -* provided because astFrameSet_ has a variable argument list which -* cannot be encapsulated in a macro (where this conversion would -* otherwise occur). -* - Because no checking or casting of arguments is performed -* before the function is invoked, the "frame" parameter is of type -* (void *) and is converted from an ID value to a pointer and -* validated within the function itself. -* - The variable argument list also prevents this function from -* invoking astFrameSet_ directly, so it must be a -* re-implementation of it in all respects, except for the -* conversions between IDs and pointers on input/output of Objects. -*/ - -/* Local Variables: */ - astDECLARE_GLOBALS /* Pointer to thread-specific global data */ - AstFrame *frame; /* Pointer to Frame structure */ - AstFrameSet *new; /* Pointer to new FrameSet */ - va_list args; /* Variable argument list */ - - int *status; - -/* Initialise. */ - new = NULL; - -/* Get a pointer to the thread specific global data structure. */ - astGET_GLOBALS(NULL); - -/* Pointer to inherited status value */ - -/* Get a pointer to the inherited status value. */ - status = astGetStatusPtr; - -/* Check the global status. */ - if ( !astOK ) return new; - -/* Obtain the Frame pointer from the ID supplied and validate the - pointer to ensure it identifies a valid Frame. */ - frame = astVerifyFrame( astMakePointer( frame_void ) ); - if ( astOK ) { - -/* Initialise the FrameSet, allocating memory and initialising the - virtual function table as well if necessary. */ - new = astInitFrameSet( NULL, sizeof( AstFrameSet ), !class_init, - &class_vtab, "FrameSet", frame ); - -/* 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 - FrameSet'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 FrameSet. */ - return astMakeId( new ); -} - -int astGetNodeId_( AstFrameSet *this, int inode, int *nnodes, - int *iframe, AstMapping **map, int *parent, - int *status ) { -/* -*+ -* Name: -* astGetNode - -* Purpose: -* Get information about a single node in a FrameSet tree. - -* Type: -* Protected virtual function. - -* Synopsis: -* #include "frameset.h" -* int astGetNode( AstFrameSet *this, int inode, int *nnodes, -* int *iframe, AstMapping **map, int *parent ) - -* Class Membership: -* FrameSet method. - -* Description: -* This function returns information about a specified node in a -* FrameSet. It is documented as protected, because it should not -* be used in general purpose software since it depends on the internal -* details of the FrameSet class. However, it is in fact public so that -* it can be used in external software that needs to know about the -* internal structure of a FrameSet (for instance, a graphical FrameSet -* visualisation system). - -* Parameters: -* this -* Pointer to the FrameSet. -* inode -* The zero-based index of the required node. -* nnodes -* Address of an int returned holding the number of nodes defined -* in the FrameSet. -* frame -* Address of a Frame pointer returned holding a pointer to a deep -* copy of the Frame, if any, associated with the node. NULL -* is returned if the node has no Frame. -* map -* Address of a Mapping pointer returned holding a pointer to a -* deep copy of the Mapping, if any, from the parent node to the -* requested node. NULL is returned if the node has no parent. -* parent -* Address of an int returned holding the zero-based index of the -* node from which the requested node is derived. -1 is returned if -* the requested node has no parent (i.e. is the root of the tree). - -* Returned Value: -* A non-zero value is returned if the "inode" value is within bounds. -* Otherwise, zero is returned. - -*- -*/ - -/* Local Variables: */ - int result; - -/* Initialise. */ - result = 0; - -/* Check the global error status. */ - if ( !astOK ) return result; - -/* Invoke the normal astGetNode_ function. */ - result = astGetNode_( this, inode, nnodes, iframe, map, parent, status ); - -/* Return an ID value for the Mapping. */ - *map = astMakeId( *map ); - -/* Return the result. */ - return result; -} - - |